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
Not this skill
| If the user wants... |
Use |
| The CLI, an SDK, or a platform integration |
infisical-setup |
| Terraform/HCL |
infisical-terraform |
| Human login via SAML/OIDC/LDAP |
infisical-sso |
| Roles, permissions, and approval policies |
infisical-access-control |
| The KMS encrypt/decrypt/sign endpoints |
infisical-kms |
| Certificate endpoints |
infisical-pki |
| Secret sync / rotation / App Connection endpoints |
the matching product skill |
This skill covers the core secrets, projects, and identities API. Product-specific endpoints are
documented in their own skills, where the surrounding concepts live.
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
/api/v4/secrets is not paginated — it returns every secret at the requested path in one response and ignores offset/limit. Scope results with secretPath, recursive, tagSlugs, or metadataFilter instead. Pagination exists on other collection endpoints (identities, memberships, certificates), which return { <resource>: [...], totalCount: n }
- Region selection — US region: us.infisical.com, EU region: eu.infisical.com
- Service tokens are deprecated — use machine identities instead
- Rate limits apply to self-hosted too — they are not cloud-only. Instance defaults are 60 reads/min, 200 writes/min, 60 secrets-ops/min, 60 auth/min per IP; self-hosted admins can change them, and cloud limits vary by plan. On a 429, honor the
retry-after header (seconds remaining, not a timestamp)
- Batch over loop — use
POST/PATCH/DELETE /api/v4/secrets/batch rather than per-secret calls; batch delete takes secrets: [{ secretKey }]
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
Quick Start
1. Authenticate with 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"
}'
Response:
{
"accessToken": "eyJ...",
"expiresIn": 3600,
"accessTokenMaxTTL": 86400,
"tokenType": "Bearer"
}
2. Use the Token for Subsequent Requests
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
Returns every secret at the path — there is no pagination on this endpoint.
curl -X GET 'https://us.infisical.com/api/v4/secrets?projectId=PROJECT_ID&environment=dev' \
-H "Authorization: Bearer TOKEN"
Add recursive=true to include subfolders:
curl -X GET 'https://us.infisical.com/api/v4/secrets?projectId=PROJECT_ID&environment=dev&secretPath=/&recursive=true' \
-H "Authorization: Bearer TOKEN"
Response is { "secrets": [...], "imports": [...] } — no total, offset, or limit keys.
Create a New Secret
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
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
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
curl -X DELETE 'https://us.infisical.com/api/v4/secrets/MY_SECRET?projectId=PROJECT_ID&environment=dev&secretPath=/' \
-H "Authorization: Bearer TOKEN"
Important Notes
- Include
Content-Type: application/json on any request that carries a JSON body
- 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 all 13 machine identity auth methods (Universal, Token, Kubernetes, GCP, AliCloud, AWS, Azure, TLS Cert, OCI, OIDC, JWT, LDAP, SPIFFE)
viewSecretValue defaults to true; set it to false when you only need key names
- The
recursive parameter on list secrets includes secrets in all subdirectories
- Beyond CRUD,
/api/v4/secrets also exposes /move, /duplicate, /batch (POST, PATCH, DELETE), /id/:secretId, and secret-reference tree endpoints
1---
2name: infisical-api
3description: Interact with the Infisical REST API to manage secrets, projects, environments, machine identities, and more. Supports secret CRUD operations, machine identity authentication, pagination, and rate limiting on cloud deployments. Not for the CLI/SDKs (infisical-setup), KMS crypto endpoints (infisical-kms), certificate endpoints (infisical-pki), or human SSO login (infisical-sso).
4triggers:
5 - infisical API
6 - REST endpoint
7 - API authentication
8 - bearer token
9 - list secrets API
10 - create secret API
11 - get secret
12 - update secret
13 - delete secret
14 - machine identity
15 - universal auth
16 - project endpoints
17 - secret operations
18metadata:
19 source: https://skillmd.com/skills/infisical/infisical-api
20---
21
22# Infisical API Skill
23
24This skill provides guidance for working with the Infisical REST API. Use it when you need to:
25- Authenticate via machine identity Universal Auth
26- List, get, create, update, or delete secrets
27- Manage projects, environments, and members
28- Work with machine identities and identity auth methods
29- Handle pagination and understand rate limits
30- Choose the correct API version and region
31
32## Not this skill
33
34| If the user wants... | Use |
35|----------------------|-----|
36| The CLI, an SDK, or a platform integration | `infisical-setup` |
37| Terraform/HCL | `infisical-terraform` |
38| **Human** login via SAML/OIDC/LDAP | `infisical-sso` |
39| Roles, permissions, and approval policies | `infisical-access-control` |
40| The KMS encrypt/decrypt/sign endpoints | `infisical-kms` |
41| Certificate endpoints | `infisical-pki` |
42| Secret sync / rotation / App Connection endpoints | the matching product skill |
43
44This skill covers the core secrets, projects, and identities API. Product-specific endpoints are
45documented in their own skills, where the surrounding concepts live.
46
47## Guiding Principles
48
491. **Always authenticate via machine identity Universal Auth first** — use the Universal Auth login endpoint to obtain a Bearer token before making other API calls
502. **Use /api/v4/secrets for secret operations** — v1/v2/v3 secret endpoints are deprecated
513. **Use /api/v1/projects, not /api/v1/workspace** — workspace endpoints are deprecated
524. **`/api/v4/secrets` is not paginated** — it returns every secret at the requested path in one response and ignores `offset`/`limit`. Scope results with `secretPath`, `recursive`, `tagSlugs`, or `metadataFilter` instead. Pagination exists on other collection endpoints (identities, memberships, certificates), which return `{ <resource>: [...], totalCount: n }`
535. **Region selection** — US region: us.infisical.com, EU region: eu.infisical.com
546. **Service tokens are deprecated** — use machine identities instead
557. **Rate limits apply to self-hosted too** — they are not cloud-only. Instance defaults are 60 reads/min, 200 writes/min, 60 secrets-ops/min, 60 auth/min per IP; self-hosted admins can change them, and cloud limits vary by plan. On a 429, honor the `retry-after` header (seconds remaining, not a timestamp)
568. **Batch over loop** — use `POST/PATCH/DELETE /api/v4/secrets/batch` rather than per-secret calls; batch delete takes `secrets: [{ secretKey }]`
57
58## Reference Files
59
60- [Authentication](./references/authentication.md) — Universal Auth login, auth endpoints, token patterns, deprecated service tokens
61- [Secrets Endpoints](./references/secrets-endpoints.md) — CRUD operations on secrets using /api/v4/secrets
62- [Projects and Identities](./references/projects-and-identities.md) — project management, environments, members, identities, groups, folders
63- [Pagination and Rate Limits](./references/pagination-and-rate-limits.md) — offset/limit pagination, cloud rate limits, content-type requirements
64
65## Quick Start
66
67### 1. Authenticate with Universal Auth
68
69```bash
70curl -X POST https://us.infisical.com/api/v1/auth/universal-auth/login \
71 -H "Content-Type: application/json" \
72 -d '{
73 "clientId": "YOUR_CLIENT_ID",
74 "clientSecret": "YOUR_CLIENT_SECRET"
75 }'
76```
77
78Response:
79```json
80{
81 "accessToken": "eyJ...",
82 "expiresIn": 3600,
83 "accessTokenMaxTTL": 86400,
84 "tokenType": "Bearer"
85}
86```
87
88### 2. Use the Token for Subsequent Requests
89
90```bash
91curl -X GET 'https://us.infisical.com/api/v4/secrets?projectId=PROJECT_ID&environment=dev' \
92 -H "Authorization: Bearer eyJ..."
93```
94
95## Common Workflows
96
97### List All Secrets in a Project
98
99Returns every secret at the path — there is no pagination on this endpoint.
100
101```bash
102curl -X GET 'https://us.infisical.com/api/v4/secrets?projectId=PROJECT_ID&environment=dev' \
103 -H "Authorization: Bearer TOKEN"
104```
105
106Add `recursive=true` to include subfolders:
107
108```bash
109curl -X GET 'https://us.infisical.com/api/v4/secrets?projectId=PROJECT_ID&environment=dev&secretPath=/&recursive=true' \
110 -H "Authorization: Bearer TOKEN"
111```
112
113Response is `{ "secrets": [...], "imports": [...] }` — no `total`, `offset`, or `limit` keys.
114
115### Create a New Secret
116
117```bash
118curl -X POST 'https://us.infisical.com/api/v4/secrets/MY_SECRET' \
119 -H "Authorization: Bearer TOKEN" \
120 -H "Content-Type: application/json" \
121 -d '{
122 "projectId": "PROJECT_ID",
123 "environment": "dev",
124 "secretPath": "/",
125 "secretValue": "super-secret-value",
126 "type": "shared"
127 }'
128```
129
130### Get a Specific Secret
131
132```bash
133curl -X GET 'https://us.infisical.com/api/v4/secrets/MY_SECRET?projectId=PROJECT_ID&environment=dev&secretPath=/' \
134 -H "Authorization: Bearer TOKEN"
135```
136
137### Update a Secret
138
139```bash
140curl -X PATCH 'https://us.infisical.com/api/v4/secrets/MY_SECRET' \
141 -H "Authorization: Bearer TOKEN" \
142 -H "Content-Type: application/json" \
143 -d '{
144 "projectId": "PROJECT_ID",
145 "environment": "dev",
146 "secretPath": "/",
147 "secretValue": "new-value"
148 }'
149```
150
151### Delete a Secret
152
153```bash
154curl -X DELETE 'https://us.infisical.com/api/v4/secrets/MY_SECRET?projectId=PROJECT_ID&environment=dev&secretPath=/' \
155 -H "Authorization: Bearer TOKEN"
156```
157
158## Important Notes
159
160- Include `Content-Type: application/json` on any request that carries a JSON body
161- Tokens expire after `expiresIn` seconds; implement refresh logic for long-running operations
162- For self-hosted deployments, replace `us.infisical.com` with your custom domain
163- Secret operations support all 13 machine identity auth methods (Universal, Token, Kubernetes, GCP, AliCloud, AWS, Azure, TLS Cert, OCI, OIDC, JWT, LDAP, SPIFFE)
164- `viewSecretValue` defaults to `true`; set it to `false` when you only need key names
165- The `recursive` parameter on list secrets includes secrets in all subdirectories
166- Beyond CRUD, `/api/v4/secrets` also exposes `/move`, `/duplicate`, `/batch` (POST, PATCH, DELETE), `/id/:secretId`, and secret-reference tree endpoints