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
403with codeadmin_key_route_forbidden. - A regular API key cannot call these endpoints. It gets
403with codeadmin_key_requiredon 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:
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.
{
"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
}
statusisactive,inactive,revoked, orexpired. Only anactivekey authenticates.kindismintedfor a key Keiro generated andregisteredfor a key you registered.access_scopeismodelsfor a regular API key andorganizationfor an admin key. Keys you create or register here are alwaysmodels.group_idis the group the key belongs to, ornullfor a key in no group.previewshows 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_atandexpires_atarenullwhen 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 parameter | Meaning |
|---|---|
limit | How many keys to return, from 1 to 100. The default is 20. |
after | The last_id of the previous page, to fetch the next one. |
group_id | Only the keys in this group. |
{
"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.
| Field | Required | Meaning |
|---|---|---|
name | Yes | A name that identifies one workload, such as production-api. |
expires_at | No | When 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_id | No | The active group to put the key in. A key stays in its group for its whole life. |
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.
| Field | Required | Meaning |
|---|---|---|
name | Yes | A name that identifies one workload. |
key | Yes | The secret to register. |
group_id | No | The 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.
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#
{
"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_idis the group this one sits in, ornullfor a group directly under your organization.depthis 1 for a group directly under your organization and one more than its parent's for any other group.external_idis your own id for the customer, such as the id your billing system uses, ornull. 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, soACMEandacmeare two different ids.statusisactiveorarchived.archived_atisnulluntil the group is archived.
Create a group#
POST /v1/organization/groups creates an active group.
| Field | Required | Meaning |
|---|---|---|
name | Yes | A name for the group, such as your customer's name. |
parent_group_id | No | The active group to create this one in. Leave it out to create the group directly under your organization. |
external_id | No | Your own id for the customer, up to 80 characters. Spaces at either end are removed. |
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 parameter | Meaning |
|---|---|
limit | How many groups to return, from 1 to 100. The default is 20. |
after | The last_id of the previous page, to fetch the next one. |
parent_group_id | Only the groups directly inside this group. |
external_id | Only 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#
| Status | Code | When |
|---|---|---|
400 | bad_request | A field is missing or invalid; param names it. |
400 | api_key_already_registered | The secret you tried to register is already registered. |
403 | admin_key_required | The request did not use an admin key. |
403 | admin_key_route_forbidden | An admin key was used for a model request. |
404 | not_found | No key or group with that id exists in your organization. |
409 | api_key_limit_reached | Your organization holds 500 active keys. |
409 | last_admin_key | The key is your organization's last active admin key. |
409 | group_external_id_taken | Another group in your organization has this external_id. |
409 | group_limit_reached | Your organization holds 10,000 active groups. |
409 | group_not_empty | The group still holds an active group or a key that is not revoked. |
429 | key_change_limit_reached | Your organization made 60 key changes in the last minute; wait for Retry-After. |
429 | platform_pressure | Key changes are briefly unavailable; wait for Retry-After. |
503 | api_key_not_yet_active | A 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.