API Keys

API keys are used to authenticate requests to the Capgo API. Keys are organization-specific and can be assigned RBAC roles for fine-grained access control. Each key can also have an optional expiration date and can be created as a “secure” (hashed) key where the plain-text value is only shown once.

Using an API key

Pass your API key in the x-api-key header of every request:

curl -H "x-api-key: YOUR_API_KEY" https://api.capgo.app/...

The authorization header is also accepted but is primarily intended for JWT tokens. When the value is a UUID-formatted API key it works, but x-api-key is the recommended header for all key types (including secure/hashed keys).

RBAC Permissions

API keys use the same role-based access control (RBAC) system as user accounts. When creating or managing keys through the web app, you assign roles at two levels:

• Organization role — Defines the key’s baseline permissions across the entire organization (e.g. org_admin, org_member).
• App roles — Optional per-app permissions (e.g. app_admin, app_developer, app_uploader, app_reader).

If an API key has explicit role bindings, only those bindings are evaluated for permission checks. The key owner’s personal permissions are not inherited by the key.

Note

Keys without role bindings fall back to a legacy mode-based system (read, upload, write, all). These modes are deprecated — use RBAC roles instead.

Secure (Hashed) Keys

When creating a secure key, the server generates the key material and returns the plain-text value once. Only a hash is stored. This means:

• The plain-text key cannot be retrieved after creation.
• Regeneration produces a new plain-text key (shown once) and updates the stored hash.
• Hashed keys are recommended for production use.

Some organizations enforce hashed keys via the enforce_hashed_api_keys org policy.

Expiration

Keys can have an optional expiration date. Expired keys are rejected at the permission check layer.

Organization policies can enforce:

• Mandatory expiration (require_apikey_expiration) — All new keys must have an expiry.
• Maximum TTL (max_apikey_expiration_days) — The expiry cannot be further than N days from now.

Security Best Practices

1. Principle of Least Privilege: Assign the most restrictive role that still allows your integration to function
2. Regular Rotation: Rotate your API keys periodically using the regenerate feature
3. Secure Storage: Store API keys securely and never commit them to version control
4. Use Hashed Keys: Create secure (hashed) keys for production integrations
5. Set Expiration: Always set an expiration date on keys used for temporary or CI/CD access
6. Scope Restrictions: Restrict keys to specific apps with the minimum required role

Common Use Cases

1. CI/CD Integration: Create keys scoped to specific apps with the app_uploader or app_developer role, and set an expiration date
2. Deployment Automation: Use keys with the app_developer role for automated deployment scripts
3. Monitoring Tools: Create keys with the app_reader role for external monitoring integrations
4. Admin Access: Use keys with the org_admin role sparingly for administrative tools
5. Third-Party Integrations: Create keys restricted to specific apps with the minimum required role