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 进行身份验证 — 使用 Universal Auth 登录端点获取 Bearer 令牌，然后再进行其他 API 调用
2. 密钥操作使用 /api/v4/secrets — v1/v2/v3 密钥端点已弃用
3. 使用 /api/v1/projects，而非 /api/v1/workspace — workspace 端点已弃用
4. /api/v4/secrets 不支持分页 — 它会在单个响应中返回请求路径下的所有密钥，并忽略 offset/limit。改用 secretPath、recursive、tagSlugs 或 metadataFilter 限定结果。其他集合端点（身份、成员资格、证书）支持分页，并返回 { <resource>: [...], totalCount: n }
5. 区域选择 — 美国区域：us.infisical.com；欧盟区域：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 分页、云端速率限制、内容类型要求

快速开始

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 和密钥引用树端点