Keys
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.
Enter your API key here (sent as Otari-Key header).
0100Only keys in this workspace.
Successful Response
Response model for key information.
falsefalseValidation Error
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 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.
Enter your API key here (sent as Otari-Key header).
Request model for creating a new API key.
Model allow-list: null = any model, [] = deny all, or canonical instance:model entries (with instance:* / instance:prefix* wildcards).
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.
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.
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.
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.
When true, requests on this key are logged with cost but never reserved, reconciled into the user's spend, or gated by budget.
falseOptional expiration timestamp
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.
falseOptional name for the key
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.
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.
Optional user ID to associate with this key
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.
Successful Response
Response model for creating a new API key.
falseValidation Error
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 details of a specific API key in the caller's organization.
Requires master key authentication.
Enter your API key here (sent as Otari-Key header).
Successful Response
Response model for key information.
falsefalseValidation Error
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 an API key in the caller's organization.
Requires master key authentication.
Enter your API key here (sent as Otari-Key header).
Request model for updating a key.
Successful Response
Response model for key information.
falsefalseValidation Error
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 (revoke) an API key in the caller's organization.
Requires master key authentication.
Enter your API key here (sent as Otari-Key header).
Successful Response
No content
Validation Error
DELETE /api/v1/keys/{key_id} HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
No content
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.
Enter your API key here (sent as Otari-Key header).
0100Only end users on this budget.
Only end users that are, or are not, blocked.
Only the end user the service names with this user value: zero or one.
Also count every matching end user, in the Otari-Total-Count response header.
falseSuccessful Response
An end user of a service key, addressed by the id the service named it by.
Validation Error
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 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.
Enter your API key here (sent as Otari-Key header).
The id the service names the end user by in a request's user field, any id, '/' included
Create an end user ahead of its first request, or move one, onto a budget on the key's list.
A budget on the key's end_user_budget_ids
Successful Response
An end user of a service key, addressed by the id the service named it by.
The end user was created
Validation Error
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"
}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.
Enter your API key here (sent as Otari-Key header).
The id the service names the end user by in a request's user field, any id, '/' included
Block, unblock or move an end user. An omitted field is left as it is.
Whether the end user is refused
A budget on the key's end_user_budget_ids to move the end user to
Successful Response
An end user of a service key, addressed by the id the service named it by.
Validation Error
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 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.
Enter your API key here (sent as Otari-Key header).
The id the service names the end user by in a request's user field
Successful Response
An end user of a service key, addressed by the id the service named it by.
Validation Error
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 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.
Enter your API key here (sent as Otari-Key header).
The id the service names the end user by in a request's user field
Create an end user ahead of its first request, or move one, onto a budget on the key's list.
A budget on the key's end_user_budget_ids
Successful Response
An end user of a service key, addressed by the id the service named it by.
The end user was created
Validation Error
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"
}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.
Enter your API key here (sent as Otari-Key header).
The id the service names the end user by in a request's user field
Block, unblock or move an end user. An omitted field is left as it is.
Whether the end user is refused
A budget on the key's end_user_budget_ids to move the end user to
Successful Response
An end user of a service key, addressed by the id the service named it by.
Validation Error
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 the identities that may authenticate as this key, oldest first.
Enter your API key here (sent as Otari-Key header).
Successful Response
A federation rule of an API key.
Whether a member gave the rule to their own key: it then matches only in the token exchange.
Validation Error
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"
}
]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.
Enter your API key here (sent as Otari-Key header).
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.
A value the token's 'aud' must contain.
The token's verified 'email', when the rule names one. Compared without regard to case.
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.
The token's 'sub', when the rule names one.
Successful Response
A federation rule of an API key.
Whether a member gave the rule to their own key: it then matches only in the token exchange.
Validation Error
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"
}Remove a federation rule. Tokens it matched stop authenticating with the next request.
Enter your API key here (sent as Otari-Key header).
Successful Response
No content
Validation Error
DELETE /api/v1/keys/{key_id}/federation-rules/{rule_id} HTTP/1.1
Otari-Key: YOUR_API_KEY
Accept: */*
No content
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.
Enter your API key here (sent as Otari-Key header).
Successful Response
Response model for creating a new API key.
falseValidation Error
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?
