---
title: "Create an API key"
canonical: "https://admiral.io/docs/api/api-keys/ApiKeyAPI_CreateApiKey"
---

# Create an API key

`POST https://api.admiral.io/v1/api-keys`

Scope: `apikey:write`

### Request body

- `api_key` (ApiKey, required): The key to create: `name`, `scopes`, and optionally `expires_at`.
  - `id` (string): Unique identifier for the key. Pattern `^key-[0-9a-z]+$`. Read-only.
  - `name` (string): URL-safe, human-readable identifier (e.g., "ci-deploy-key"), unique among the caller's keys. Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63.
  - `scopes` (array of string): The scopes granted to this key, and the ceiling on any access token minted from it. Must be a subset of the caller's own scopes. Items at most 255.
  - `status` (ApiKeyStatus): ApiKeyStatus represents the lifecycle state of an API key. One of `API_KEY_STATUS_UNSPECIFIED`, `API_KEY_STATUS_ACTIVE`, `API_KEY_STATUS_REVOKED`. Read-only.
  - `expires_at` (Timestamp): (IMMUTABLE) When the key expires. Unset never expires. Fixed at creation; tenant policy may cap it.
  - `last_used_at` (Timestamp): When the key was last exchanged for an access token. Minted tokens are reused for their lifetime, so this reads as "still in use" at that granularity, not as the time of the last request. Read-only.
  - `revoked_at` (Timestamp): Set when the key was revoked. Read-only.
  - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this. Read-only.
    - `id` (string): The actor's typed id: a `usr-` user id or an `sa-` service account id.
    - `display_name` (string): Human-readable name (e.g., "John Smith", "deploy-bot").
    - `email` (string): Email address (empty for non-human actors).
  - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only.

### Response 200

Success

- `api_key` (ApiKey): The created key metadata.
  - `id` (string): Unique identifier for the key. Pattern `^key-[0-9a-z]+$`. Read-only.
  - `name` (string): URL-safe, human-readable identifier (e.g., "ci-deploy-key"), unique among the caller's keys. Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length 1 to 63.
  - `scopes` (array of string): The scopes granted to this key, and the ceiling on any access token minted from it. Must be a subset of the caller's own scopes. Items at most 255.
  - `status` (ApiKeyStatus): ApiKeyStatus represents the lifecycle state of an API key. One of `API_KEY_STATUS_UNSPECIFIED`, `API_KEY_STATUS_ACTIVE`, `API_KEY_STATUS_REVOKED`. Read-only.
  - `expires_at` (Timestamp): (IMMUTABLE) When the key expires. Unset never expires. Fixed at creation; tenant policy may cap it.
  - `last_used_at` (Timestamp): When the key was last exchanged for an access token. Minted tokens are reused for their lifetime, so this reads as "still in use" at that granularity, not as the time of the last request. Read-only.
  - `revoked_at` (Timestamp): Set when the key was revoked. Read-only.
  - `created_by` (ActorRef): ActorRef is a lightweight reference to the user or agent that performed an action. Server-populated on all resource responses. Clients should never send this. Read-only.
    - `id` (string): The actor's typed id: a `usr-` user id or an `sa-` service account id.
    - `display_name` (string): Human-readable name (e.g., "John Smith", "deploy-bot").
    - `email` (string): Email address (empty for non-human actors).
  - `created_at` (Timestamp): A point in time in RFC 3339 format, with up to nanosecond precision. Output uses UTC (`Z`); input may use an offset from UTC. Read-only.
- `secret` (string): The raw secret, shown exactly once and never again. It reads `admp_<id suffix>_<secret>`: the key `key-8r3t6w1y4n9z` has a secret starting `admp_8r3t6w1y4n9z_`, so a secret found anywhere names its key.