infisical-api

Infisical API スキル

このスキルは、Infisical REST API を扱うためのガイダンスを提供します。次のような場合に使用してください:

• マシンアイデンティティの Universal Auth で認証する
• シークレットの一覧取得、取得、作成、更新、削除を行う
• プロジェクト、環境、メンバーを管理する
• マシンアイデンティティとアイデンティティ認証方式を扱う
• ページネーションを処理し、レート制限を理解する
• 正しい API バージョンとリージョンを選択する

このスキルではないもの

ユーザーが求めるもの...	使用するもの
CLI、SDK、またはプラットフォーム統合	infisical-setup
Terraform/HCL	infisical-terraform
SAML/OIDC/LDAP による人間のログイン	infisical-sso
ロール、権限、承認ポリシー	infisical-access-control
KMS の暗号化/復号/署名エンドポイント	infisical-kms
証明書エンドポイント	infisical-pki
シークレット同期 / ローテーション / App Connection エンドポイント	対応する製品スキル

このスキルは、コアとなるシークレット、プロジェクト、アイデンティティの API を対象としています。製品固有のエンドポイントは、 その周辺の概念が存在するそれぞれのスキルでドキュメント化されています。

基本原則

1. 常に最初にマシンアイデンティティの Universal Auth で認証する — 他の API 呼び出しを行う前に、Universal Auth ログインエンドポイントを使用して Bearer トークンを取得します
2. シークレット操作には /api/v4/secrets を使用する — v1/v2/v3 のシークレットエンドポイントは非推奨です
3. /api/v1/workspace ではなく /api/v1/projects を使用する — workspace エンドポイントは非推奨です
4. /api/v4/secrets はページネーションされません — 指定されたパスにあるすべてのシークレットを 1 つのレスポンスで返し、offset/limit を無視します。代わりに secretPath、recursive、tagSlugs、または metadataFilter で結果を絞り込んでください。ページネーションは他のコレクションエンドポイント(アイデンティティ、メンバーシップ、証明書)に存在し、それらは { <resource>: [...], totalCount: n } を返します
5. リージョンの選択 — US リージョン: us.infisical.com、EU リージョン: eu.infisical.com
6. サービス トークンは非推奨です — 代わりにマシンアイデンティティを使用してください
7. レート制限はセルフホストにも適用されます — クラウド専用ではありません。インスタンスのデフォルトは IP あたり読み取り 60/分、書き込み 200/分、シークレット操作 60/分、認証 60/分です。セルフホストの管理者はこれらを変更でき、クラウドの制限はプランによって異なります。429 の場合は、retry-after ヘッダー(タイムスタンプではなく残り秒数)に従ってください
8. ループよりバッチ — シークレットごとの呼び出しではなく、POST/PATCH/DELETE /api/v4/secrets/batch を使用してください。バッチ削除は secrets: [{ secretKey }] を受け取ります

リファレンスファイル

• 認証 — Universal Auth ログイン、認証エンドポイント、トークンパターン、非推奨のサービス トークン
• シークレットエンドポイント — /api/v4/secrets を使用したシークレットの CRUD 操作
• プロジェクトとアイデンティティ — プロジェクト管理、環境、メンバー、アイデンティティ、グループ、フォルダ
• ページネーションとレート制限 — offset/limit ページネーション、クラウドのレート制限、content-type の要件

クイックスタート

1. Universal Auth で認証する

curl -X POST https://us.infisical.com/api/v1/auth/universal-auth/login \
  -H "Content-Type: application/json" \
  -d '{
    "clientId": "YOUR_CLIENT_ID",
    "clientSecret": "YOUR_CLIENT_SECRET"
  }'

レスポンス:

{
  "accessToken": "eyJ...",
  "expiresIn": 3600,
  "accessTokenMaxTTL": 86400,
  "tokenType": "Bearer"
}

2. 後続のリクエストにトークンを使用する

curl -X GET 'https://us.infisical.com/api/v4/secrets?projectId=PROJECT_ID&environment=dev' \
  -H "Authorization: Bearer eyJ..."

一般的なワークフロー

プロジェクト内のすべてのシークレットを一覧表示する

指定されたパスにあるすべてのシークレットを返します — このエンドポイントにはページネーションはありません。

curl -X GET 'https://us.infisical.com/api/v4/secrets?projectId=PROJECT_ID&environment=dev' \
  -H "Authorization: Bearer TOKEN"

サブフォルダを含めるには recursive=true を追加します:

curl -X GET 'https://us.infisical.com/api/v4/secrets?projectId=PROJECT_ID&environment=dev&secretPath=/&recursive=true' \
  -H "Authorization: Bearer TOKEN"

レスポンスは { "secrets": [...], "imports": [...] } です — total、offset、limit キーはありません。

新しいシークレットを作成する

curl -X POST 'https://us.infisical.com/api/v4/secrets/MY_SECRET' \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "PROJECT_ID",
    "environment": "dev",
    "secretPath": "/",
    "secretValue": "super-secret-value",
    "type": "shared"
  }'

特定のシークレットを取得する

curl -X GET 'https://us.infisical.com/api/v4/secrets/MY_SECRET?projectId=PROJECT_ID&environment=dev&secretPath=/' \
  -H "Authorization: Bearer TOKEN"

シークレットを更新する

curl -X PATCH 'https://us.infisical.com/api/v4/secrets/MY_SECRET' \
  -H "Authorization: Bearer TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "PROJECT_ID",
    "environment": "dev",
    "secretPath": "/",
    "secretValue": "new-value"
  }'

シークレットを削除する

curl -X DELETE 'https://us.infisical.com/api/v4/secrets/MY_SECRET?projectId=PROJECT_ID&environment=dev&secretPath=/' \
  -H "Authorization: Bearer TOKEN"

重要な注意事項

• JSON ボディを伴うすべてのリクエストには Content-Type: application/json を含めてください
• トークンは expiresIn 秒後に期限切れになるため、長時間実行される操作にはリフレッシュ処理を実装してください
• セルフホスト環境では、us.infisical.com を独自のカスタムドメインに置き換えてください
• シークレット操作は 13 種類すべてのマシンアイデンティティ認証方式（Universal、Token、Kubernetes、GCP、AliCloud、AWS、Azure、TLS Cert、OCI、OIDC、JWT、LDAP、SPIFFE）をサポートしています
• viewSecretValue はデフォルトで true です。キー名のみが必要な場合は false に設定してください
• シークレット一覧取得時の recursive パラメータは、すべてのサブディレクトリ内のシークレットを含めます
• CRUD に加えて、/api/v4/secrets は /move、/duplicate、/batch（POST、PATCH、DELETE）、/id/:secretId、およびシークレット参照ツリーのエンドポイントも公開しています