> Markdown version of https://authpi.com/docs/reference/core-api/api-keys/ — fetch the complete AuthPI docs index at https://authpi.com/llms.txt to discover all available pages.

# API Keys — AuthPI Core API

Organization API key management. API keys allow organizations to authenticate programmatically for service-to-service communication.

## 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) |
| `status` | active \| blocked \| revoked \| expired \| suspended | Optional | Filter by key status |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Paginated list of API keys | `object` |
| 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) |
| `status` | active \| blocked \| revoked \| expired \| suspended | Optional | Filter by key status |

### Responses

| Code | Description | Schema |
| --- | --- | --- |
| 200 | Paginated list of API keys | `object` |
| 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`

| 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 |  |
| `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` |
| 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:**
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

### 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` |