API Keys — Core API

Lists all API keys for an organization.

API keys allow organizations to authenticate programmatically for service-to-service communication without user context.

Key statuses:

• active - Key can be used for authentication
• blocked - Temporarily disabled (can be unblocked)
• revoked - Permanently disabled

Use the status filter to find blocked or revoked keys for auditing.

Creates a new API key for an organization.

API keys enable service-to-service authentication for backend integrations. They authenticate as the organization (not a specific user).

Use cases:

• Backend services calling your API
• CI/CD pipelines
• Automated scripts and cron jobs
• Third-party integrations

Security:

• Limit scopes to the minimum required
• Set an expiration for production keys
• Rotate keys regularly

Important: The secret is only returned once at creation. Store it securely - it cannot be retrieved again.

Lists the API keys that authenticate against this account on the AuthPI Admin API.

These keys are used with HTTP Basic auth (key_id:secret) for programmatic access to all account resources — issuers, users, clients, webhooks, and more.

Key statuses:

• active - Key can be used for authentication
• blocked - Temporarily disabled (can be unblocked)
• revoked - Permanently disabled

Use the status filter to find blocked or revoked keys for auditing.

Creates an API key that authenticates against this account on the AuthPI Admin API.

Use the key with HTTP Basic auth (key_id:secret) for service-to-service access to account resources without user context.

Use cases:

• Backend services managing users, clients, or webhooks
• CI/CD pipelines
• Automated scripts and cron jobs

Security:

• Limit scopes to the minimum required (e.g. issuers.users:read)
• Set an expiration for production keys
• Rotate keys regularly

Important: The secret is only returned once at creation. Store it securely - it cannot be retrieved again.

Retrieves the details of a specific API key.

Returns key metadata including name, scopes, status, and usage information. The secret is never returned after creation.

Updates an API key's metadata.

You can update the name, description, tags, scopes, and expiration. To rotate the secret, use the dedicated Rotate API Key Secret endpoint.

Note: Reducing scopes takes effect immediately for new requests.

Deletes an API key permanently.

This immediately revokes the key and prevents any further authentication attempts using it. The key data is retained for 31 days before permanent deletion.

Note: This is equivalent to revoking the key with immediate effect.

Rotates the secret for an API key.

The old secret remains valid for 15 minutes to allow for graceful transitions in distributed systems.

Rotation process:

1. New secret is generated and returned
2. Old secret remains valid for 15 minutes
3. Update your services to use the new secret
4. After 15 minutes, only the new secret works

Best practices:

• Rotate secrets periodically (e.g., every 90 days)
• Rotate immediately if a secret may have been compromised
• Store the new secret securely - it cannot be retrieved again

Temporarily blocks an API key.

Use blocking to disable a key while investigating suspicious activity or during maintenance, without permanently revoking it.

When blocked:

• Authentication attempts immediately fail
• The key can be unblocked later to restore access

Use cases:

• Suspected compromise investigation
• Temporary maintenance windows
• Testing key rotation before committing

Unblocks a previously blocked API key.

After unblocking, the key immediately becomes active again and can be used for authentication.

Note: Only blocked keys can be unblocked. Revoked keys cannot be restored.

Permanently revokes an API key.

This immediately and permanently disables the key. Unlike blocking, revocation cannot be undone.

What happens:

• Authentication attempts immediately fail
• The key status changes to "revoked"
• Key data is retained for 31 days for auditing, then permanently deleted

Use cases:

• Key compromised or leaked
• Integration permanently decommissioned
• Employee offboarding

Alternative: If you need temporary suspension, use Block API Key instead.