API Keys — Core API
Organization API key management. API keys allow organizations to authenticate programmatically for service-to-service communication.
Base URL: https://api.authpi.com — explore every endpoint in the
interactive Core API reference.
GET/v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/api-keys
List API Keys
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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | The unique identifier of the account |
issuer_id | string | Required | The unique identifier of the issuer |
org_id | string | Required | The unique identifier of the organization |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | Maximum number of items to return (1-100, default: 50) |
cursor | string | Optional | Pagination cursor (key ID from previous response) |
q | string | Optional | |
status | active | blocked | revoked | expired | suspended | Optional | active: usable; blocked: temporarily disabled; revoked: permanently disabled; expired: past expiry; suspended: temporarily disabled for risk/investigation |
access | full | write | read | none | Optional | |
readiness | action | review | ready | Optional |
Responses
| Code | Description | Schema |
|---|---|---|
| 200 | Paginated list of API keys | object |
| 400 | Bad Request - The request is malformed or contains invalid data. | ApiError |
| 401 | Unauthorized - Authentication is required or has failed. | ApiError |
| 403 | Forbidden - You don't have permission to perform this action. | ApiError |
POST/v1/accounts/{account_id}/issuers/{issuer_id}/organizations/{org_id}/api-keys
Create API Key
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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | The unique identifier of the account |
issuer_id | string | Required | The unique identifier of the issuer |
org_id | string | Required | The unique identifier of the organization |
Request body
Content type: application/json
| Property | Type | Required | Description |
|---|---|---|---|
name | string | Required | A name for the resource. |
description | string | Optional | |
tags | string[] | Optional | |
restrictions | object | Required | |
expires_at | integer | Optional | Unix timestamp in milliseconds |
metadata | Metadata | Optional | |
type | api_key | Required | |
secret | string | Optional | |
secret_hint | string | Optional |
Responses
| Code | Description | Schema |
|---|---|---|
| 201 | API key created successfully. Store the secret securely - it's only returned once. | object |
| 400 | Bad Request - The request is malformed or contains invalid data. | ApiError |
| 401 | Unauthorized - Authentication is required or has failed. | ApiError |
| 403 | Forbidden - You don't have permission to perform this action. | ApiError |
| 404 | Not Found - The requested resource does not exist. | ApiError |
| 429 | Too Many Requests - Rate limit or resource limit exceeded. | ApiError |
GET/v1/accounts/{account_id}/api-keys
List Account API Keys
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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | The unique identifier of the account |
Query parameters
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | Optional | Maximum number of items to return (1-100, default: 50) |
cursor | string | Optional | Pagination cursor (key ID from previous response) |
q | string | Optional | |
status | active | blocked | revoked | expired | suspended | Optional | active: usable; blocked: temporarily disabled; revoked: permanently disabled; expired: past expiry; suspended: temporarily disabled for risk/investigation |
access | full | write | read | none | Optional | |
readiness | action | review | ready | Optional |
Responses
| Code | Description | Schema |
|---|---|---|
| 200 | Paginated list of API keys | object |
| 400 | Bad Request - The request is malformed or contains invalid data. | ApiError |
| 401 | Unauthorized - Authentication is required or has failed. | ApiError |
| 403 | Forbidden - You don't have permission to perform this action. | ApiError |
POST/v1/accounts/{account_id}/api-keys
Create Account API Key
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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | The unique identifier of the account |
Request body
Content type: application/json
Schema: CreateAccountApiKey
Responses
| Code | Description | Schema |
|---|---|---|
| 201 | API key created successfully. Store the secret securely - it's only returned once. | object |
| 400 | Bad Request - The request is malformed or contains invalid data. | ApiError |
| 401 | Unauthorized - Authentication is required or has failed. | ApiError |
| 403 | Forbidden - You don't have permission to perform this action. | ApiError |
| 429 | Too Many Requests - Rate limit or resource limit exceeded. | ApiError |
GET/v1/accounts/{account_id}/api-keys/{key_id}
Get API Key
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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | The unique identifier of the account |
key_id | string | Required | The unique identifier of the API key |
Responses
| Code | Description | Schema |
|---|---|---|
| 200 | API key retrieved successfully | object |
| 401 | Unauthorized - Authentication is required or has failed. | ApiError |
| 403 | Forbidden - You don't have permission to perform this action. | ApiError |
| 404 | Not Found - The requested resource does not exist. | ApiError |
PATCH/v1/accounts/{account_id}/api-keys/{key_id}
Update API Key
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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | The unique identifier of the account |
key_id | string | Required | The unique identifier of the API key |
Request body
Content type: application/json
Schema: UpdateApiKey
Responses
| Code | Description | Schema |
|---|---|---|
| 200 | API key updated successfully | object |
| 400 | Bad Request - The request is malformed or contains invalid data. | ApiError |
| 401 | Unauthorized - Authentication is required or has failed. | ApiError |
| 403 | Forbidden - You don't have permission to perform this action. | ApiError |
| 404 | Not Found - The requested resource does not exist. | ApiError |
| 412 | Precondition Failed - The resource has been modified since the provided ETag. | PreconditionFailedError |
DELETE/v1/accounts/{account_id}/api-keys/{key_id}
Delete API Key
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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | The unique identifier of the account |
key_id | string | Required | The unique identifier of the API key |
Responses
| Code | Description | Schema |
|---|---|---|
| 204 | No Content - The operation completed successfully with no response body. | — |
| 401 | Unauthorized - Authentication is required or has failed. | ApiError |
| 403 | Forbidden - You don't have permission to perform this action. | ApiError |
| 404 | Not Found - The requested resource does not exist. | ApiError |
| 412 | Precondition Failed - The resource has been modified since the provided ETag. | PreconditionFailedError |
POST/v1/accounts/{account_id}/api-keys/{key_id}/rotate
Rotate API Key Secret
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:
- New secret is generated and returned
- Old secret remains valid for 15 minutes
- Update your services to use the new secret
- 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
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | The unique identifier of the account |
key_id | string | Required | The unique identifier of the API key |
Request body
Content type: application/json
| Property | Type | Required | Description |
|---|---|---|---|
new_secret | string | Optional | |
hint | string | Optional |
Responses
| Code | Description | Schema |
|---|---|---|
| 200 | Secret rotated successfully. Store the new secret securely. | object |
| 400 | Bad Request - The request is malformed or contains invalid data. | ApiError |
| 401 | Unauthorized - Authentication is required or has failed. | ApiError |
| 403 | Forbidden - You don't have permission to perform this action. | ApiError |
| 404 | Not Found - The requested resource does not exist. | ApiError |
POST/v1/accounts/{account_id}/api-keys/{key_id}/block
Block API Key
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
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | The unique identifier of the account |
key_id | string | Required | The unique identifier of the API key |
Request body
Content type: application/json
| Property | Type | Required | Description |
|---|---|---|---|
by | string | Optional | |
reason | string | Optional |
Responses
| Code | Description | Schema |
|---|---|---|
| 200 | API key blocked successfully | object |
| 400 | Bad Request - The request is malformed or contains invalid data. | ApiError |
| 401 | Unauthorized - Authentication is required or has failed. | ApiError |
| 403 | Forbidden - You don't have permission to perform this action. | ApiError |
| 404 | Not Found - The requested resource does not exist. | ApiError |
POST/v1/accounts/{account_id}/api-keys/{key_id}/unblock
Unblock API Key
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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | The unique identifier of the account |
key_id | string | Required | The unique identifier of the API key |
Responses
| Code | Description | Schema |
|---|---|---|
| 200 | API key unblocked successfully | object |
| 401 | Unauthorized - Authentication is required or has failed. | ApiError |
| 403 | Forbidden - You don't have permission to perform this action. | ApiError |
| 404 | Not Found - The requested resource does not exist. | ApiError |
POST/v1/accounts/{account_id}/api-keys/{key_id}/revoke
Revoke API Key
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.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
account_id | string | Required | The unique identifier of the account |
key_id | string | Required | The unique identifier of the API key |
Request body
Content type: application/json
| Property | Type | Required | Description |
|---|---|---|---|
by | string | Optional | |
reason | string | Optional |
Responses
| Code | Description | Schema |
|---|---|---|
| 200 | API key revoked successfully | object |
| 400 | Bad Request - The request is malformed or contains invalid data. | ApiError |
| 401 | Unauthorized - Authentication is required or has failed. | ApiError |
| 403 | Forbidden - You don't have permission to perform this action. | ApiError |
| 404 | Not Found - The requested resource does not exist. | ApiError |