Organization API

The organization API lets you manage your organization's API keys with an API call instead of the Keiro console. You can list keys, create keys, register a key you already hold, and revoke keys, and group keys by your own customers.

On this page 1 of 16

Admin keys#

Every organization API request uses an admin key. An admin key manages the organization it belongs to and nothing else:

  • It can call only the endpoints on this page. A model request made with an admin key returns 403 with code admin_key_route_forbidden.
  • A regular API key cannot call these endpoints. It gets 403 with code admin_key_required on every path that starts with /v1/organization/, including paths this page does not list.
  • Keys you create or register here are regular API keys. They call models and cannot manage keys.

Admin keys are issued by Keiro support, not by this API. To get one, contact support from the Status and support page. Store an admin key the way you store any other secret, and keep it out of the workloads that call models.

Send the admin key as a bearer token, exactly like a regular key:

Run a curl request Shell
printf 'Keiro admin key: '
IFS= read -rs KEIRO_BEARER
printf '\n'

curl -sS https://api.keirolabs.ai/v1/organization/api_keys \
  -H @- <<<"Authorization: Bearer $KEIRO_BEARER" | python3 -m json.tool

The key object#

Every endpoint returns keys in the same shape, and never returns a key's secret except once, when this API creates it.

JSON payload JSON
{
  "id": "key_8f14e45fceea167a5a36dedd4bea2543",
  "name": "production-api",
  "preview": "keiro_sk_...Xy9Q",
  "status": "active",
  "created_at": "2026-11-12T18:04:31.120934+00:00",
  "last_used_at": null,
  "expires_at": "2027-01-31T00:00:00+00:00",
  "kind": "minted",
  "access_scope": "models",
  "group_id": null
}
  • status is active, inactive, revoked, or expired. Only an active key authenticates.
  • kind is minted for a key Keiro generated and registered for a key you registered.
  • access_scope is models for a regular API key and organization for an admin key. Keys you create or register here are always models.
  • group_id is the group the key belongs to, or null for a key in no group.
  • preview shows the last four characters of the secret. For a registered key it is … followed by those four characters.
  • Timestamps are ISO 8601 with a time zone. last_used_at and expires_at are null when they do not apply.

List keys#

GET /v1/organization/api_keys returns your organization's keys, newest first. It does not list the console's own chat key.

Query parameterMeaning
limitHow many keys to return, from 1 to 100. The default is 20.
afterThe last_id of the previous page, to fetch the next one.
group_idOnly the keys in this group.
JSON payload JSON
{
  "object": "list",
  "data": [
    {
      "id": "key_8f14e45fceea167a5a36dedd4bea2543",
      "name": "production-api",
      "preview": "keiro_sk_...Xy9Q",
      "status": "active",
      "created_at": "2026-11-12T18:04:31.120934+00:00",
      "last_used_at": null,
      "expires_at": null,
      "kind": "minted",
      "access_scope": "models",
      "group_id": null
    }
  ],
  "first_id": "key_8f14e45fceea167a5a36dedd4bea2543",
  "last_id": "key_8f14e45fceea167a5a36dedd4bea2543",
  "has_more": false
}

When has_more is true, request the next page with after set to last_id.

Create a key#

POST /v1/organization/api_keys creates a regular API key and returns its secret in key. This is the only time the secret is shown, so save it to your secret manager before you discard the response.

FieldRequiredMeaning
nameYesA name that identifies one workload, such as production-api.
expires_atNoWhen the key expires, as an ISO 8601 timestamp with a time zone, such as 2027-01-31T00:00:00Z. The key stops authenticating within a minute after this time. It must be in the future and at most ten years away, and is returned in UTC.
group_idNoThe active group to put the key in. A key stays in its group for its whole life.
Run a curl request Shell
printf 'Keiro admin key: '
IFS= read -rs KEIRO_BEARER
printf '\n'

curl -sS https://api.keirolabs.ai/v1/organization/api_keys \
  -H "Content-Type: application/json" \
  -d '{"name": "production-api"}' \
  -H @- <<<"Authorization: Bearer $KEIRO_BEARER" | python3 -m json.tool

The response is 201 with the key object plus key, the secret.

Register a key you already hold#

POST /v1/organization/api_keys/register attaches a secret you generated yourself, so a workload can keep the credential it already has. Keiro stores only a SHA-256 hash of the secret and its last four characters. It never stores, logs, or returns the secret, and the response does not echo it.

FieldRequiredMeaning
nameYesA name that identifies one workload.
keyYesThe secret to register.
group_idNoThe active group to put the key in. A key stays in its group for its whole life.

The secret must:

  • be 32 to 128 characters long
  • use only printable ASCII characters, with no spaces or other whitespace
  • not be very repetitive: its characters must carry at least 3 bits of Shannon entropy each, counted from how often each character occurs. This rejects strings such as one character repeated, but it does not tell whether a string is guessable, so generate the secret with a cryptographic random source, for example openssl rand -base64 48
  • not already exist in another organization, or in yours in any state other than active

Each rule that fails returns 400 with a message naming it. A secret that already exists returns code api_key_already_registered, whether another organization holds it or your organization holds it inactive or expired. A key your organization revoked cannot be registered again; register a new secret instead.

Run a curl request Shell
printf 'Keiro admin key: '
IFS= read -rs KEIRO_BEARER
printf '\n'
printf 'Key to register: '
IFS= read -rs KEY_TO_REGISTER
printf '\n'

printf '{"name": "batch-worker", "key": "%s"}' "$KEY_TO_REGISTER" \
  | curl -sS https://api.keirolabs.ai/v1/organization/api_keys/register \
    -H "Content-Type: application/json" \
    --data-binary @- \
    -H @<(printf 'Authorization: Bearer %s\n' "$KEIRO_BEARER") | python3 -m json.tool

The secret goes into the JSON body as it is, so if it contains " or \, escape those characters as JSON requires.

The response is 201 with the key object, with kind set to registered. Registering is safe to repeat: sending a secret that is already an active key in your organization creates nothing and returns 200 with that key exactly as it is, whatever name the request carries. That holds for any active key your organization holds, including one Keiro generated and an admin key, as long as the request names the key's own group, or no group for a key in none. Naming a different group returns 400 with code api_key_already_registered.

A 503 with code api_key_not_yet_active means the key is saved but not yet active on every server. Every server picks up key changes on its own, usually within a minute, so the key starts working without further action, and sending the same request again is safe and returns the key once it is saved.

Revoke a key#

DELETE /v1/organization/api_keys/{api_key_id} revokes one of your organization's keys. Revoking is permanent: the key cannot be reactivated, and it stops authenticating within a minute of the response. Revoking a key that is already revoked returns it unchanged, so a retried request is safe.

The response is 200 with the revoked key object.

Revoking your organization's last active admin key returns 409 with code last_admin_key. Ask support for another admin key first.

Groups#

A group stands for one of your own customers. Put that customer's keys in its group, and every request made with those keys is recorded against the group. Groups nest: a group sits directly under your organization or inside another group, at most five levels deep, so a customer can have its own customers or teams. Your organization pays for the usage of every group in it.

The group object#

JSON payload JSON
{
  "id": "grp_1679091c5a880faf6fb5e6087eb1b2dc",
  "name": "Acme Corp",
  "parent_group_id": null,
  "depth": 1,
  "external_id": "cus_4821",
  "status": "active",
  "created_at": "2026-11-14T18:04:31.120934+00:00",
  "archived_at": null
}
  • parent_group_id is the group this one sits in, or null for a group directly under your organization.
  • depth is 1 for a group directly under your organization and one more than its parent's for any other group.
  • external_id is your own id for the customer, such as the id your billing system uses, or null. No two groups in your organization share one, archived groups included. It is compared exactly: once spaces at either end are removed, case and every other character count, so ACME and acme are two different ids.
  • status is active or archived. archived_at is null until the group is archived.

Create a group#

POST /v1/organization/groups creates an active group.

FieldRequiredMeaning
nameYesA name for the group, such as your customer's name.
parent_group_idNoThe active group to create this one in. Leave it out to create the group directly under your organization.
external_idNoYour own id for the customer, up to 80 characters. Spaces at either end are removed.
Run a curl request Shell
printf 'Keiro admin key: '
IFS= read -rs KEIRO_BEARER
printf '\n'

curl -sS https://api.keirolabs.ai/v1/organization/groups \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "external_id": "cus_4821"}' \
  -H @- <<<"Authorization: Bearer $KEIRO_BEARER" | python3 -m json.tool

The response is 201 with the group object. A parent_group_id that is not an active group in your organization, or a parent already five levels deep, returns 400 with param set to parent_group_id. An external_id another group already has, archived or not, returns 409 with code group_external_id_taken.

List groups#

GET /v1/organization/groups returns your organization's groups, archived ones included, newest first, in the same page shape as the key list.

Query parameterMeaning
limitHow many groups to return, from 1 to 100. The default is 20.
afterThe last_id of the previous page, to fetch the next one.
parent_group_idOnly the groups directly inside this group.
external_idOnly the group with this external_id.

Get a group#

GET /v1/organization/groups/{group_id} returns one group.

Archive a group#

DELETE /v1/organization/groups/{group_id} archives a group. An archived group stays in the list, takes no new keys or groups, and cannot be made active again. It keeps its external_id, so a new group cannot reuse that external_id. Archiving a group that is already archived returns it unchanged.

A group that still holds an active group, or any key that is not revoked, returns 409 with code group_not_empty. That includes inactive and expired keys, because either can be made to work again: an inactive key can be reactivated and an expired key can be given a new expiry. Archive the groups inside it and revoke its keys first.

Keys in groups#

Create or register a key with group_id to put it in a group, and list one group's keys with the group_id query parameter. A key's group is set when the key is created and never changes; to move a workload to another group, create a key there and revoke the old one. Rotating a key gives the new key the old key's group, and leaves the old key inactive in that group until you revoke it.

Limits#

An organization can hold at most 500 active API keys. The count includes every active key in the organization, including keys created in the console. Creating or registering a key beyond that returns 409 with code api_key_limit_reached; revoke keys you no longer use to make room.

An organization can make at most 60 key changes a minute through this API. Creating, registering, and revoking a key each count as one change; listing keys does not. A change beyond that returns 429 with code key_change_limit_reached and a Retry-After header that says how long to wait.

An organization can hold at most 10,000 active groups. Creating a group beyond that returns 409 with code group_limit_reached; archive groups you no longer use to make room. Creating and archiving groups do not count as key changes.

Organization API requests also count toward your organization's request rate limit, like any other request. See Rate and spend limits.

Errors#

StatusCodeWhen
400bad_requestA field is missing or invalid; param names it.
400api_key_already_registeredThe secret you tried to register is already registered.
403admin_key_requiredThe request did not use an admin key.
403admin_key_route_forbiddenAn admin key was used for a model request.
404not_foundNo key or group with that id exists in your organization.
409api_key_limit_reachedYour organization holds 500 active keys.
409last_admin_keyThe key is your organization's last active admin key.
409group_external_id_takenAnother group in your organization has this external_id.
409group_limit_reachedYour organization holds 10,000 active groups.
409group_not_emptyThe group still holds an active group or a key that is not revoked.
429key_change_limit_reachedYour organization made 60 key changes in the last minute; wait for Retry-After.
429platform_pressureKey changes are briefly unavailable; wait for Retry-After.
503api_key_not_yet_activeA registered key is saved but not yet active everywhere; it starts working on its own, and sending the same request again is safe.

Every endpoint acts only on the organization that owns the admin key. A key or group id from another organization returns 404, or 400 where a request field names it. See Errors for the error body shape.

Search Keiro docs

Start typing to search pages and sections.

Start typing to search pages and sections.

Documentation

Console