> Keiro Labs API documentation - Organization API
> Page: https://docs.keirolabs.ai/organization-api.html
> Markdown: https://docs.keirolabs.ai/organization-api.md
> Agent index: https://docs.keirolabs.ai/llms.txt
> API base URL: https://api.keirolabs.ai/v1
> Auth: send "Authorization: Bearer <api-key>" with a key created in the
> Keiro console (https://console.keirolabs.ai/api-keys). Use credentials saved by
> `keiro setup`, or resolve the key from a secret manager or an owner-only
> secret file and pass it to the client explicitly. Never read another
> provider's variable, and never put raw key material in environment
> variables, code, docs, or logs.

# Organization API

The organization API lets you manage your organization's API keys with an API
call instead of the [Keiro console](https://console.keirolabs.ai/api-keys). You
can list keys, create keys, register a key you already hold, and revoke keys,
and group keys by your own customers.

## 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](status-support.md) 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:

```bash
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
{
  "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](#groups) 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 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. |

```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.

| 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. |

```bash
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.

```bash
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
{
  "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.

| 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. |

```bash
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](rate-and-spend-limits.md).

## 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](errors.md) for the error
body shape.

## Related pages

- [API keys](api-keys.md)
- [API auth](api-auth.md)
- [Errors](errors.md)
