For the complete documentation index, see llms.txt. This page is also available as Markdown.

Keys

List Keys

get

List the API keys in the caller's organization.

Requires master key authentication. An unset workspace_id lists every key in that organization; naming a workspace in another one lists nothing rather than refusing, so the filter reports no more than the unfiltered read does.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Query parameters
skipintegerOptionalDefault: 0
limitinteger · min: 1 · max: 1000OptionalDefault: 100
workspace_idstring · uuid · nullableOptional

Only keys in this workspace.

Responses
200

Successful Response

application/json

Response model for key information.

allowed_modelsstring[] · nullableRequired
allowed_toolsstring[] · nullableRequired
capture_agent_telemetryboolean · nullableRequired
config_namestring · nullableOptional
created_atstringRequired
end_user_budget_idstring · nullableRequired
end_user_budget_idsstring[]Required
exclude_from_budgetbooleanRequired
expires_atstring · nullableRequired
idstringRequired
is_activebooleanRequired
is_organization_service_keybooleanOptionalDefault: false
is_service_keybooleanRequired
key_namestring · nullableRequired
key_prefixstring · nullableRequired
key_suffixstring · nullableRequired
last_used_atstring · nullableRequired
max_end_usersinteger · nullableOptional
operator_disabledbooleanOptionalDefault: false
reject_user_mismatchboolean · nullableRequired
user_idstring · nullableRequired
workspace_idstring · uuidRequired
get/api/v1/keys
GET /api/v1/keys HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
[
  {
    "allowed_models": [
      "text"
    ],
    "allowed_tools": [
      "text"
    ],
    "capture_agent_telemetry": true,
    "config_name": "text",
    "created_at": "text",
    "end_user_budget_id": "text",
    "end_user_budget_ids": [
      "text"
    ],
    "exclude_from_budget": true,
    "expires_at": "text",
    "id": "text",
    "is_active": true,
    "is_organization_service_key": false,
    "is_service_key": true,
    "key_name": "text",
    "key_prefix": "text",
    "key_suffix": "text",
    "last_used_at": "text",
    "max_end_users": 1,
    "metadata": {
      "ANY_ADDITIONAL_PROPERTY": "anything"
    },
    "operator_disabled": false,
    "reject_user_mismatch": true,
    "user_id": "text",
    "workspace_id": "123e4567-e89b-12d3-a456-426614174000"
  }
]

Create Key

post

Create a new API key in the caller's organization.

Requires master key authentication.

If user_id is provided, the key will be associated with that user (creates user if it doesn't exist). If user_id is not provided, the key is associated with the shared "default" user, which is created on first use. Keys without an explicit owner therefore share one identity, and so share budget, usage, and files.

workspace_id names a workspace in the caller's organization, and omitting it mints into that organization's default workspace. A key resolves that organization's provider credentials and bills there, so minting into another organization's workspace would spend its budget on its credentials.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Body

Request model for creating a new API key.

allowed_modelsstring[] · nullableOptional

Model allow-list: null = any model, [] = deny all, or canonical instance:model entries (with instance:* / instance:prefix* wildcards).

allowed_toolsstring[] · nullableOptional

Tool allow-list for POST /api/v1/search and /api/v1/fetch: null = inherit the user's, [] = no tool, or search and fetch tool names ('*' for every tool). A model wildcard never grants a tool.

capture_agent_telemetryboolean · nullableOptional

Per-key override of the deployment-wide capture_agent_telemetry setting: null (default) inherits it, true always stores this key's coding-agent telemetry, false always discards it. Covers both behavioral events (tool_result, tool_decision, user_prompt, api_error) from POST /otlp/v1/logs and outcome-metric data points (lines of code, commits, pull requests, active time) from POST /otlp/v1/metrics. Usage capture and billing are unaffected either way.

end_user_budget_idstring · nullableOptional

Budget each end user this key creates is capped at, unless the request names another with Otari-End-User-Budget. Null leaves end users capped only by this key's own ceiling.

end_user_budget_idsstring[] · max: 100 · nullableOptional

Budgets a request may start a new end user on by naming one in Otari-End-User-Budget. Null allows end_user_budget_id alone. When both are set, end_user_budget_id must be on the list.

exclude_from_budgetbooleanOptional

When true, requests on this key are logged with cost but never reserved, reconciled into the user's spend, or gated by budget.

Default: false
expires_atstring · date-time · nullableOptional

Optional expiration timestamp

is_service_keybooleanOptional

When true, a request may name an end user in its 'user' field. Each end user is created on first use, owned by this key's user, and billed to its own budget, while this key's own ceiling caps all of them together.

Default: false
key_namestring · nullableOptional

Optional name for the key

max_end_usersinteger · nullableOptional

Most live end users this key may have on the budgets it assigns (all of its owner's end users when it assigns none). A request that would create one more is refused with 403 and end_user_limit_reached; deleting end users frees room. Null is no cap.

reject_user_mismatchboolean · nullableOptional

Per-key override of the deployment-wide reject_user_mismatch setting: null (default) inherits it, true always rejects a request naming a different 'user', false always accepts it. Spend binds to this key's own user either way.

user_idstring · nullableOptional

Optional user ID to associate with this key

workspace_idstring · uuid · nullableOptional

Workspace this key belongs to, which must be one in the caller's organization. Omitted means that organization's default workspace. A key belongs to exactly one workspace: requests on it are scoped and billed there, so the workspace is read off the key rather than off a request header.

Responses
200

Successful Response

application/json

Response model for creating a new API key.

allowed_modelsstring[] · nullableRequired
allowed_toolsstring[] · nullableRequired
capture_agent_telemetryboolean · nullableRequired
created_atstringRequired
end_user_budget_idstring · nullableRequired
end_user_budget_idsstring[]Required
exclude_from_budgetbooleanRequired
expires_atstring · nullableRequired
idstringRequired
is_activebooleanRequired
is_organization_service_keybooleanOptionalDefault: false
is_service_keybooleanRequired
keystringRequired
key_namestring · nullableRequired
key_prefixstring · nullableRequired
key_suffixstring · nullableRequired
max_end_usersinteger · nullableRequired
reject_user_mismatchboolean · nullableRequired
user_idstring · nullableRequired
post/api/v1/keys
POST /api/v1/keys HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 418

{
  "allowed_models": [
    "text"
  ],
  "allowed_tools": [
    "text"
  ],
  "capture_agent_telemetry": true,
  "end_user_budget_id": "text",
  "end_user_budget_ids": [
    "text"
  ],
  "exclude_from_budget": false,
  "expires_at": "2026-01-01T00:00:00.000Z",
  "is_service_key": false,
  "key_name": "text",
  "max_end_users": 1,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "reject_user_mismatch": true,
  "user_id": "text",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}
{
  "allowed_models": [
    "text"
  ],
  "allowed_tools": [
    "text"
  ],
  "capture_agent_telemetry": true,
  "created_at": "text",
  "end_user_budget_id": "text",
  "end_user_budget_ids": [
    "text"
  ],
  "exclude_from_budget": true,
  "expires_at": "text",
  "id": "text",
  "is_active": true,
  "is_organization_service_key": false,
  "is_service_key": true,
  "key": "text",
  "key_name": "text",
  "key_prefix": "text",
  "key_suffix": "text",
  "max_end_users": 1,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "reject_user_mismatch": true,
  "user_id": "text"
}

Get Key

get

Get details of a specific API key in the caller's organization.

Requires master key authentication.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
key_idstringRequired
Responses
200

Successful Response

application/json

Response model for key information.

allowed_modelsstring[] · nullableRequired
allowed_toolsstring[] · nullableRequired
capture_agent_telemetryboolean · nullableRequired
config_namestring · nullableOptional
created_atstringRequired
end_user_budget_idstring · nullableRequired
end_user_budget_idsstring[]Required
exclude_from_budgetbooleanRequired
expires_atstring · nullableRequired
idstringRequired
is_activebooleanRequired
is_organization_service_keybooleanOptionalDefault: false
is_service_keybooleanRequired
key_namestring · nullableRequired
key_prefixstring · nullableRequired
key_suffixstring · nullableRequired
last_used_atstring · nullableRequired
max_end_usersinteger · nullableOptional
operator_disabledbooleanOptionalDefault: false
reject_user_mismatchboolean · nullableRequired
user_idstring · nullableRequired
workspace_idstring · uuidRequired
get/api/v1/keys/{key_id}
GET /api/v1/keys/{key_id} HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
{
  "allowed_models": [
    "text"
  ],
  "allowed_tools": [
    "text"
  ],
  "capture_agent_telemetry": true,
  "config_name": "text",
  "created_at": "text",
  "end_user_budget_id": "text",
  "end_user_budget_ids": [
    "text"
  ],
  "exclude_from_budget": true,
  "expires_at": "text",
  "id": "text",
  "is_active": true,
  "is_organization_service_key": false,
  "is_service_key": true,
  "key_name": "text",
  "key_prefix": "text",
  "key_suffix": "text",
  "last_used_at": "text",
  "max_end_users": 1,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "operator_disabled": false,
  "reject_user_mismatch": true,
  "user_id": "text",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}

Update Key

patch

Update an API key in the caller's organization.

Requires master key authentication.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
key_idstringRequired
Body

Request model for updating a key.

allowed_modelsstring[] · nullableOptional
allowed_toolsstring[] · nullableOptional
capture_agent_telemetryboolean · nullableOptional
end_user_budget_idstring · nullableOptional
end_user_budget_idsstring[] · max: 100 · nullableOptional
exclude_from_budgetboolean · nullableOptional
expires_atstring · date-time · nullableOptional
is_activeboolean · nullableOptional
is_service_keyboolean · nullableOptional
key_namestring · nullableOptional
max_end_usersinteger · nullableOptional
reject_user_mismatchboolean · nullableOptional
Responses
200

Successful Response

application/json

Response model for key information.

allowed_modelsstring[] · nullableRequired
allowed_toolsstring[] · nullableRequired
capture_agent_telemetryboolean · nullableRequired
config_namestring · nullableOptional
created_atstringRequired
end_user_budget_idstring · nullableRequired
end_user_budget_idsstring[]Required
exclude_from_budgetbooleanRequired
expires_atstring · nullableRequired
idstringRequired
is_activebooleanRequired
is_organization_service_keybooleanOptionalDefault: false
is_service_keybooleanRequired
key_namestring · nullableRequired
key_prefixstring · nullableRequired
key_suffixstring · nullableRequired
last_used_atstring · nullableRequired
max_end_usersinteger · nullableOptional
operator_disabledbooleanOptionalDefault: false
reject_user_mismatchboolean · nullableRequired
user_idstring · nullableRequired
workspace_idstring · uuidRequired
patch/api/v1/keys/{key_id}
PATCH /api/v1/keys/{key_id} HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 362

{
  "allowed_models": [
    "text"
  ],
  "allowed_tools": [
    "text"
  ],
  "capture_agent_telemetry": true,
  "end_user_budget_id": "text",
  "end_user_budget_ids": [
    "text"
  ],
  "exclude_from_budget": true,
  "expires_at": "2026-01-01T00:00:00.000Z",
  "is_active": true,
  "is_service_key": true,
  "key_name": "text",
  "max_end_users": 1,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "reject_user_mismatch": true
}
{
  "allowed_models": [
    "text"
  ],
  "allowed_tools": [
    "text"
  ],
  "capture_agent_telemetry": true,
  "config_name": "text",
  "created_at": "text",
  "end_user_budget_id": "text",
  "end_user_budget_ids": [
    "text"
  ],
  "exclude_from_budget": true,
  "expires_at": "text",
  "id": "text",
  "is_active": true,
  "is_organization_service_key": false,
  "is_service_key": true,
  "key_name": "text",
  "key_prefix": "text",
  "key_suffix": "text",
  "last_used_at": "text",
  "max_end_users": 1,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "operator_disabled": false,
  "reject_user_mismatch": true,
  "user_id": "text",
  "workspace_id": "123e4567-e89b-12d3-a456-426614174000"
}

Delete Key

delete

Delete (revoke) an API key in the caller's organization.

Requires master key authentication.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
key_idstringRequired
Responses
204

Successful Response

No content

delete/api/v1/keys/{key_id}
DELETE /api/v1/keys/{key_id} HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*

No content

List End Users

get

List the end users of a service key, oldest first.

End users belong to the key's user, so every service key of one user lists the same end users. A deleted end user is not listed. external_id reads one end user by any id, one containing '/' included, as a list of zero or one.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
key_idstringRequired
Query parameters
skipintegerOptionalDefault: 0
limitinteger · min: 1 · max: 1000OptionalDefault: 100
budget_idstring · nullableOptional

Only end users on this budget.

blockedboolean · nullableOptional

Only end users that are, or are not, blocked.

external_idstring · nullableOptional

Only the end user the service names with this user value: zero or one.

include_totalbooleanOptional

Also count every matching end user, in the Otari-Total-Count response header.

Default: false
Responses
200

Successful Response

application/json

An end user of a service key, addressed by the id the service named it by.

blockedbooleanRequired
budget_idstring · nullableRequired
budget_started_atstring · nullableRequired
created_atstringRequired
current_requestsintegerRequired
current_tokensintegerRequired
external_idstringRequired
next_budget_reset_atstring · nullableRequired
owner_user_idstringRequired
reservednumberRequired
spendnumberRequired
user_idstringRequired
get/api/v1/keys/{key_id}/end-users
GET /api/v1/keys/{key_id}/end-users HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
[
  {
    "blocked": true,
    "budget_id": "text",
    "budget_started_at": "text",
    "created_at": "text",
    "current_requests": 1,
    "current_tokens": 1,
    "external_id": "text",
    "next_budget_reset_at": "text",
    "owner_user_id": "text",
    "reserved": 1,
    "spend": 1,
    "user_id": "text"
  }
]

Put End User By Query

put

Put the end user named by external_id on a budget from the key's list, creating it if it does not exist yet.

The same as PUT /keys/{key_id}/end-users/{external_id}, for any id, one containing '/' included.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
key_idstringRequired
Query parameters
external_idstring · min: 1Required

The id the service names the end user by in a request's user field, any id, '/' included

Body

Create an end user ahead of its first request, or move one, onto a budget on the key's list.

budget_idstring · min: 1Required

A budget on the key's end_user_budget_ids

Responses
200

Successful Response

application/json

An end user of a service key, addressed by the id the service named it by.

blockedbooleanRequired
budget_idstring · nullableRequired
budget_started_atstring · nullableRequired
created_atstringRequired
current_requestsintegerRequired
current_tokensintegerRequired
external_idstringRequired
next_budget_reset_atstring · nullableRequired
owner_user_idstringRequired
reservednumberRequired
spendnumberRequired
user_idstringRequired
put/api/v1/keys/{key_id}/end-users
PUT /api/v1/keys/{key_id}/end-users?external_id=text HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "budget_id": "text"
}
{
  "blocked": true,
  "budget_id": "text",
  "budget_started_at": "text",
  "created_at": "text",
  "current_requests": 1,
  "current_tokens": 1,
  "external_id": "text",
  "next_budget_reset_at": "text",
  "owner_user_id": "text",
  "reserved": 1,
  "spend": 1,
  "user_id": "text"
}

Update End User By Query

patch

Block, unblock or move the end user of a service key named by external_id.

The same as PATCH /keys/{key_id}/end-users/{external_id}, for any id, one containing '/' included.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
key_idstringRequired
Query parameters
external_idstring · min: 1Required

The id the service names the end user by in a request's user field, any id, '/' included

Body

Block, unblock or move an end user. An omitted field is left as it is.

blockedboolean · nullableOptional

Whether the end user is refused

budget_idstring · min: 1 · nullableOptional

A budget on the key's end_user_budget_ids to move the end user to

Responses
200

Successful Response

application/json

An end user of a service key, addressed by the id the service named it by.

blockedbooleanRequired
budget_idstring · nullableRequired
budget_started_atstring · nullableRequired
created_atstringRequired
current_requestsintegerRequired
current_tokensintegerRequired
external_idstringRequired
next_budget_reset_atstring · nullableRequired
owner_user_idstringRequired
reservednumberRequired
spendnumberRequired
user_idstringRequired
patch/api/v1/keys/{key_id}/end-users
PATCH /api/v1/keys/{key_id}/end-users?external_id=text HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 35

{
  "blocked": true,
  "budget_id": "text"
}
{
  "blocked": true,
  "budget_id": "text",
  "budget_started_at": "text",
  "created_at": "text",
  "current_requests": 1,
  "current_tokens": 1,
  "external_id": "text",
  "next_budget_reset_at": "text",
  "owner_user_id": "text",
  "reserved": 1,
  "spend": 1,
  "user_id": "text"
}

Get End User

get

Get an end user of a service key by the id the service names it by.

End users belong to the key's user, so every service key of one user reaches the same end users. An id with a '.' or '..' segment is refused with 400; GET /keys/{key_id}/end-users?external_id= reads any end user.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
key_idstringRequired
external_idstringRequired

The id the service names the end user by in a request's user field

Responses
200

Successful Response

application/json

An end user of a service key, addressed by the id the service named it by.

blockedbooleanRequired
budget_idstring · nullableRequired
budget_started_atstring · nullableRequired
created_atstringRequired
current_requestsintegerRequired
current_tokensintegerRequired
external_idstringRequired
next_budget_reset_atstring · nullableRequired
owner_user_idstringRequired
reservednumberRequired
spendnumberRequired
user_idstringRequired
get/api/v1/keys/{key_id}/end-users/{external_id}
GET /api/v1/keys/{key_id}/end-users/{external_id} HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
{
  "blocked": true,
  "budget_id": "text",
  "budget_started_at": "text",
  "created_at": "text",
  "current_requests": 1,
  "current_tokens": 1,
  "external_id": "text",
  "next_budget_reset_at": "text",
  "owner_user_id": "text",
  "reserved": 1,
  "spend": 1,
  "user_id": "text"
}

Put End User

put

Put an end user of a service key on a budget from the key's list, creating it if it does not exist yet.

Answers 201 when the end user was created, so one can be placed on a budget before its first request. An end user already on the budget keeps its current period, so repeating the call changes nothing. A budget that is not on the key's end_user_budget_ids is refused with 403 and end_user_budget_not_allowed. An id with a '.' or '..' segment is refused with 400; PUT /keys/{key_id}/end-users?external_id= takes any id.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
key_idstringRequired
external_idstringRequired

The id the service names the end user by in a request's user field

Body

Create an end user ahead of its first request, or move one, onto a budget on the key's list.

budget_idstring · min: 1Required

A budget on the key's end_user_budget_ids

Responses
200

Successful Response

application/json

An end user of a service key, addressed by the id the service named it by.

blockedbooleanRequired
budget_idstring · nullableRequired
budget_started_atstring · nullableRequired
created_atstringRequired
current_requestsintegerRequired
current_tokensintegerRequired
external_idstringRequired
next_budget_reset_atstring · nullableRequired
owner_user_idstringRequired
reservednumberRequired
spendnumberRequired
user_idstringRequired
put/api/v1/keys/{key_id}/end-users/{external_id}
PUT /api/v1/keys/{key_id}/end-users/{external_id} HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 20

{
  "budget_id": "text"
}
{
  "blocked": true,
  "budget_id": "text",
  "budget_started_at": "text",
  "created_at": "text",
  "current_requests": 1,
  "current_tokens": 1,
  "external_id": "text",
  "next_budget_reset_at": "text",
  "owner_user_id": "text",
  "reserved": 1,
  "spend": 1,
  "user_id": "text"
}

Update End User

patch

Block, unblock or move an end user of a service key.

A move restarts the end user's period on the new budget but keeps what it has spent and used so far, as the users API does. The budget must be on the key's end_user_budget_ids. An id with a '.' or '..' segment is refused with 400; PATCH /keys/{key_id}/end-users?external_id= takes any id.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
key_idstringRequired
external_idstringRequired

The id the service names the end user by in a request's user field

Body

Block, unblock or move an end user. An omitted field is left as it is.

blockedboolean · nullableOptional

Whether the end user is refused

budget_idstring · min: 1 · nullableOptional

A budget on the key's end_user_budget_ids to move the end user to

Responses
200

Successful Response

application/json

An end user of a service key, addressed by the id the service named it by.

blockedbooleanRequired
budget_idstring · nullableRequired
budget_started_atstring · nullableRequired
created_atstringRequired
current_requestsintegerRequired
current_tokensintegerRequired
external_idstringRequired
next_budget_reset_atstring · nullableRequired
owner_user_idstringRequired
reservednumberRequired
spendnumberRequired
user_idstringRequired
patch/api/v1/keys/{key_id}/end-users/{external_id}
PATCH /api/v1/keys/{key_id}/end-users/{external_id} HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 35

{
  "blocked": true,
  "budget_id": "text"
}
{
  "blocked": true,
  "budget_id": "text",
  "budget_started_at": "text",
  "created_at": "text",
  "current_requests": 1,
  "current_tokens": 1,
  "external_id": "text",
  "next_budget_reset_at": "text",
  "owner_user_id": "text",
  "reserved": 1,
  "spend": 1,
  "user_id": "text"
}

List Federation Rules

get

List the identities that may authenticate as this key, oldest first.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
key_idstringRequired
Responses
200

Successful Response

application/json

A federation rule of an API key.

api_key_idstringRequired
audiencestringRequired
created_atstring · date-timeRequired
emailstring · nullableRequired
idstringRequired
issuerstringRequired
member_managedbooleanRequired

Whether a member gave the rule to their own key: it then matches only in the token exchange.

subjectstring · nullableRequired
get/api/v1/keys/{key_id}/federation-rules
GET /api/v1/keys/{key_id}/federation-rules HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
[
  {
    "api_key_id": "text",
    "audience": "text",
    "created_at": "2026-01-01T00:00:00.000Z",
    "email": "text",
    "id": "text",
    "issuer": "text",
    "member_managed": true,
    "subject": "text"
  }
]

Create Federation Rule

post

Let an OpenID Connect identity token authenticate as this key, in place of its secret.

The issuer must be one of the deployment's federation_issuers, else 400. A token authenticates when it is signed by that issuer, its aud contains audience, and it carries the rule's subject and verified email, whichever the rule sets. A rule naming the identity of an existing rule answers 409: the same issuer, audience, subject and email on this key, or on another key the same issuer and audience with a subject or email in common and no contradicting value.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
key_idstringRequired
Body

An OpenID Connect identity that may authenticate as the key, in place of its secret.

A token matches when it is signed by issuer, names audience among its audiences, and carries each of subject and email that the rule sets; an email matches only when the token marks it verified. At least one of the two is required.

audiencestring · min: 1 · max: 512Required

A value the token's 'aud' must contain.

emailstring · min: 3 · max: 320 · nullableOptional

The token's verified 'email', when the rule names one. Compared without regard to case.

issuerstring · min: 1 · max: 512Required

The token's 'iss'. On an operator's rule, one of the deployment's federation_issuers; on a member's own key, any https issuer, whose discovery document and signing keys are fetched only from a public host.

subjectstring · min: 1 · max: 255 · nullableOptional

The token's 'sub', when the rule names one.

Responses
201

Successful Response

application/json

A federation rule of an API key.

api_key_idstringRequired
audiencestringRequired
created_atstring · date-timeRequired
emailstring · nullableRequired
idstringRequired
issuerstringRequired
member_managedbooleanRequired

Whether a member gave the rule to their own key: it then matches only in the token exchange.

subjectstring · nullableRequired
post/api/v1/keys/{key_id}/federation-rules
POST /api/v1/keys/{key_id}/federation-rules HTTP/1.1
Otari-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 136

{
  "audience": "https://otari.example.com",
  "email": "hackbot-api@my-project.iam.gserviceaccount.com",
  "issuer": "https://accounts.google.com"
}
{
  "api_key_id": "text",
  "audience": "text",
  "created_at": "2026-01-01T00:00:00.000Z",
  "email": "text",
  "id": "text",
  "issuer": "text",
  "member_managed": true,
  "subject": "text"
}

Delete Federation Rule

delete

Remove a federation rule. Tokens it matched stop authenticating with the next request.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
key_idstringRequired
rule_idstringRequired
Responses
204

Successful Response

No content

delete/api/v1/keys/{key_id}/federation-rules/{rule_id}
DELETE /api/v1/keys/{key_id}/federation-rules/{rule_id} HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*

No content

Rotate Key

post

Rotate an API key's secret in place, within the caller's organization.

Requires master key authentication.

Generates a new secret for the same key row (id, user, name, expiry, and metadata are preserved) and returns the new raw key once, using the same response shape as key creation. The previous secret stops authenticating immediately; there is no grace window.

Authorizations
Otari-KeystringRequired

Enter your API key here (sent as Otari-Key header).

Path parameters
key_idstringRequired
Responses
200

Successful Response

application/json

Response model for creating a new API key.

allowed_modelsstring[] · nullableRequired
allowed_toolsstring[] · nullableRequired
capture_agent_telemetryboolean · nullableRequired
created_atstringRequired
end_user_budget_idstring · nullableRequired
end_user_budget_idsstring[]Required
exclude_from_budgetbooleanRequired
expires_atstring · nullableRequired
idstringRequired
is_activebooleanRequired
is_organization_service_keybooleanOptionalDefault: false
is_service_keybooleanRequired
keystringRequired
key_namestring · nullableRequired
key_prefixstring · nullableRequired
key_suffixstring · nullableRequired
max_end_usersinteger · nullableRequired
reject_user_mismatchboolean · nullableRequired
user_idstring · nullableRequired
post/api/v1/keys/{key_id}/rotate
POST /api/v1/keys/{key_id}/rotate HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
{
  "allowed_models": [
    "text"
  ],
  "allowed_tools": [
    "text"
  ],
  "capture_agent_telemetry": true,
  "created_at": "text",
  "end_user_budget_id": "text",
  "end_user_budget_ids": [
    "text"
  ],
  "exclude_from_budget": true,
  "expires_at": "text",
  "id": "text",
  "is_active": true,
  "is_organization_service_key": false,
  "is_service_key": true,
  "key": "text",
  "key_name": "text",
  "key_prefix": "text",
  "key_suffix": "text",
  "max_end_users": 1,
  "metadata": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "reject_user_mismatch": true,
  "user_id": "text"
}

Last updated

Was this helpful?