---
title: "Register an issuer"
canonical: "https://admiral.io/docs/api/issuers/IssuerAPI_CreateIssuer"
---

# Register an issuer

`POST https://api.admiral.io/v1/issuers`

Scope: `serviceaccount:write`

### Request body

- `issuer` (Issuer, required): The issuer to create: `name`, `iss` and `keys`.
  - `id` (string): Pattern `^iss-[0-9a-z]+$`. Read-only.
  - `name` (string): One made at enrollment is named after the agent that enrolled it. Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length at most 63.
  - `iss` (string): (IMMUTABLE) The `iss` every token must carry, exactly, e.g. `https://token.actions.githubusercontent.com`. One made at enrollment takes it from the enrolling token. Fixed once set. Length 1 to 2048.
  - `keys` (IssuerKeys, required): IssuerKeys is where Admiral gets the keys that verify an issuer's tokens.
    - Exactly one of `jwks_uri`, `jwks`, `reported` is set.
    - `jwks` (string): A JSON Web Key Set, pasted in. It replaces the trusted set, so paste the whole set the issuer serves: during a rotation that holds the old key and the new one. Length 2 to 65536.
    - `jwks_uri` (string (uri)): Fetched and refreshed when a token names a key not yet seen. Rotation needs no action. string.prefix = "https://" Length at most 2048.
    - `reported` (Reported): The first keys arrive when an agent enrolls. Keys agents report after that wait in `pending_key_ids` for an admin to accept. Never set on create: an issuer with reported keys is made only by enrollment.
  - `key_ids` (array of string): The key ids currently trusted. Read-only.
  - `keys_updated_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.
  - `pending_key_ids` (array of string): Key ids an agent reported that are not trusted yet. They are never applied on their own: an admin accepts them with SetIssuerKeys. Read-only.
  - `pending_keys_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.
  - `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

- `issuer` (Issuer): Issuer is a set of keys Admiral accepts tokens from. A token must carry this `iss`, be issued for Admiral as its audience, and verify against the issuer's keys.
  - `id` (string): Pattern `^iss-[0-9a-z]+$`. Read-only.
  - `name` (string): One made at enrollment is named after the agent that enrolled it. Pattern `^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$`. Length at most 63.
  - `iss` (string): (IMMUTABLE) The `iss` every token must carry, exactly, e.g. `https://token.actions.githubusercontent.com`. One made at enrollment takes it from the enrolling token. Fixed once set. Length 1 to 2048.
  - `keys` (IssuerKeys, required): IssuerKeys is where Admiral gets the keys that verify an issuer's tokens.
    - Exactly one of `jwks_uri`, `jwks`, `reported` is set.
    - `jwks` (string): A JSON Web Key Set, pasted in. It replaces the trusted set, so paste the whole set the issuer serves: during a rotation that holds the old key and the new one. Length 2 to 65536.
    - `jwks_uri` (string (uri)): Fetched and refreshed when a token names a key not yet seen. Rotation needs no action. string.prefix = "https://" Length at most 2048.
    - `reported` (Reported): The first keys arrive when an agent enrolls. Keys agents report after that wait in `pending_key_ids` for an admin to accept. Never set on create: an issuer with reported keys is made only by enrollment.
  - `key_ids` (array of string): The key ids currently trusted. Read-only.
  - `keys_updated_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.
  - `pending_key_ids` (array of string): Key ids an agent reported that are not trusted yet. They are never applied on their own: an admin accepts them with SetIssuerKeys. Read-only.
  - `pending_keys_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.
  - `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.