API Keys

Overview

The API Keys API lets you manage programmatic access credentials for your organization. API keys are used in the Authorization: Bearer header to authenticate requests. All endpoints require authentication.

The full API key is returned only once at creation time. Store it securely — it cannot be retrieved again.

Create API Key

POST /api/v1/api-keys
Authorization: Bearer aira_live_xxxxx

Creates a new API key for your organization. The full key is returned in the response and is never shown again.

Request Body

Field	Type	Required	Description
`name`	string	Yes	A human-readable label for this key (1-100 characters)

Example Request

curl -X POST https://api.aira.com/api/v1/api-keys \
  -H "Authorization: Bearer aira_live_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{ "name": "CI Pipeline" }'

Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "CI Pipeline",
  "key": "aira_live_abc123...",
  "key_prefix": "aira_live_abc1",
  "scopes": ["*"],
  "created_at": "2026-06-05T10:00:00Z",
  "request_id": "req_01J8X..."
}

Response Fields

Field	Type	Description
`id`	string	Unique identifier of the API key
`name`	string	The label you provided
`key`	string	The full API key (shown only once)
`key_prefix`	string	First characters of the key, used for identification
`scopes`	array	Permission scopes granted to this key
`created_at`	string	When the key was created (ISO 8601 UTC)
`request_id`	string	Unique request identifier for support reference

List API Keys

GET /api/v1/api-keys
Authorization: Bearer aira_live_xxxxx

Returns all API keys for your organization. The secret key value is never included — only the prefix is shown for identification.

Example Response

{
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "CI Pipeline",
      "key_prefix": "aira_live_abc1",
      "scopes": ["*"],
      "last_used_at": "2026-06-05T09:45:00Z",
      "expires_at": null,
      "revoked_at": null,
      "created_at": "2026-06-01T10:00:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 1,
    "total": 1,
    "has_more": false
  },
  "request_id": "req_01J8X..."
}

Key Fields

Field	Type	Description
`id`	string	Unique identifier of the API key
`name`	string	The label assigned at creation
`key_prefix`	string	First characters of the key, used for identification
`scopes`	array	Permission scopes granted to this key
`last_used_at`	string\|null	When the key was last used for authentication
`expires_at`	string\|null	When the key expires, or `null` if it does not expire
`revoked_at`	string\|null	When the key was revoked, or `null` if still active
`created_at`	string	When the key was created (ISO 8601 UTC)

Revoke API Key

DELETE /api/v1/api-keys/{key_id}
Authorization: Bearer aira_live_xxxxx

Permanently revokes an API key. Any request using this key after revocation will receive a 401 Unauthorized response.

Path Parameters

Parameter	Type	Description
`key_id`	string	The UUID of the API key to revoke

Example Request

curl -X DELETE https://api.aira.com/api/v1/api-keys/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer aira_live_xxxxx"

Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "revoked_at": "2026-06-05T14:30:00Z",
  "request_id": "req_01J8X..."
}

Response Fields

Field	Type	Description
`id`	string	The revoked API key's identifier
`revoked_at`	string	When the key was revoked (ISO 8601 UTC)
`request_id`	string	Unique request identifier for support reference

Revocation is permanent. Create a new API key if you need to restore access.

API Keys

On this page