infisical-api

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

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

1. Always authenticate via machine identity Universal Auth first — use the Universal Auth login endpoint to obtain a Bearer token before making other API calls
2. Use /api/v4/secrets for secret operations — v1/v2/v3 secret endpoints are deprecated
3. Use /api/v1/projects, not /api/v1/workspace — workspace endpoints are deprecated
4. /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 }
5. Region selection — US region: us.infisical.com, EU region: eu.infisical.com
6. Service tokens are deprecated — use machine identities instead
7. 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)
8. Batch over loop — use POST/PATCH/DELETE /api/v4/secrets/batch rather than per-secret calls; batch delete takes secrets: [{ secretKey }]