infisical-api

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Infisical API Skill

This skill provides guidance for working with the Infisical REST API. Use it when you need to:

Authenticate via machine identity Universal Auth
List, get, create, update, or delete secrets
Manage projects, environments, and members
Work with machine identities and identity auth methods
Handle pagination and understand rate limits
Choose the correct API version and region

这个技能为使用Infisical REST API提供指导。当你需要以下操作时可以使用它：

通过机器身份Universal Auth进行认证
列出、获取、创建、更新或删除密钥
管理项目、环境和成员
处理机器身份和身份认证方式
处理分页并了解速率限制
选择正确的API版本和区域

Guiding Principles

指导原则

Always authenticate via machine identity Universal Auth first — use the Universal Auth login endpoint to obtain a Bearer token before making other API calls
Use /api/v4/secrets for secret operations — v1/v2/v3 secret endpoints are deprecated
Use /api/v1/projects, not /api/v1/workspace — workspace endpoints are deprecated
Pagination uses offset/limit — default limit is 20, maximum is 100
Region selection — US region: us.infisical.com, EU region: eu.infisical.com
Service tokens are deprecated — use machine identities instead
Rate limits apply to cloud only — self-hosted deployments have no rate limits; free tier: 200 reads/min, pro tier: 350 reads/min

始终先通过机器身份Universal Auth进行认证 — 在进行其他API调用之前，使用Universal Auth登录端点获取Bearer令牌
使用/api/v4/secrets进行密钥操作 — v1/v2/v3密钥端点已被弃用
使用/api/v1/projects，而非/api/v1/workspace — workspace端点已被弃用
分页使用offset/limit — 默认限制为20，最大为100
区域选择 — 美国区域：us.infisical.com，欧盟区域：eu.infisical.com
服务令牌已被弃用 — 使用机器身份替代
速率限制仅适用于云版本 — 自托管部署无速率限制；免费层：200次读取/分钟，专业层：350次读取/分钟

Reference Files

参考文件

Authentication — Universal Auth login, auth endpoints, token patterns, deprecated service tokens
Secrets Endpoints — CRUD operations on secrets using /api/v4/secrets
Projects and Identities — project management, environments, members, identities, groups, folders
Pagination and Rate Limits — offset/limit pagination, cloud rate limits, content-type requirements

认证 — Universal Auth登录、认证端点、令牌模式、已弃用的服务令牌
密钥端点 — 使用/api/v4/secrets进行密钥的CRUD操作
项目与身份 — 项目管理、环境、成员、身份、群组、文件夹
分页与速率限制 — offset/limit分页、云速率限制、内容类型要求

Quick Start

快速开始

1. Authenticate with Universal Auth

1. 使用Universal Auth认证

bash

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"
  }'

Response:

json

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

bash

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"
  }'

响应：

json

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

2. Use the Token for Subsequent Requests

2. 使用令牌进行后续请求

bash

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

bash

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

Common Workflows

常见工作流

List All Secrets in a Project

列出项目中的所有密钥

bash

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

bash

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

Create a New Secret

创建新密钥

bash

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"
  }'

bash

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"
  }'

Get a Specific Secret

获取特定密钥

bash

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

bash

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

Update a Secret

更新密钥

bash

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"
  }'

bash

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"
  }'

Delete a Secret

删除密钥

bash

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

bash

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

Important Notes

重要注意事项

All requests must include
```
Content-Type: application/json
```
header
Tokens expire after
```
expiresIn
```
seconds; implement refresh logic for long-running operations
For self-hosted deployments, replace
```
us.infisical.com
```
with your custom domain
Secret operations support multiple auth types (AWS, Azure, GCP, Kubernetes, OIDC, JWT, LDAP)
Use
```
viewSecretValue=true
```
when listing secrets if you need to see actual values
The
```
recursive
```
parameter on list secrets endpoint includes secrets in all subdirectories

所有请求必须包含
```
Content-Type: application/json
```
请求头
令牌会在
```
expiresIn
```
秒后过期；对于长时间运行的操作，请实现刷新逻辑
对于自托管部署，请将
```
us.infisical.com
```
替换为你的自定义域名
密钥操作支持多种认证类型（AWS、Azure、GCP、Kubernetes、OIDC、JWT、LDAP）
如果需要查看实际密钥值，在列出密钥时使用
```
viewSecretValue=true
```
参数
列出密钥端点的
```
recursive
```
参数会包含所有子目录中的密钥