Sign in
keys

Create Key

Changed on

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.

post/api/v1/keys

Request

  • The document declares no server URL.
  • Auth: one of:
    • API key in header Otari-Key
    • API key in header x-api-key

Request body

allowed_modelsstring[] nullable

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

capture_agent_telemetryboolean nullable

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 nullable

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[] nullable

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_budgetboolean

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

expires_atstring date-time nullable

Optional expiration timestamp

is_service_keyboolean

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.

key_namestring nullable

Optional name for the key

metadataobject

Optional metadata

reject_user_mismatchboolean nullable

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 nullable

Optional user ID to associate with this key

workspace_idstring uuid nullable

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.

Response

Successful Response

allowed_modelsstring[] nullable required
capture_agent_telemetryboolean nullable required
created_atstring required
end_user_budget_idstring nullable required
end_user_budget_idsstring[] required
exclude_from_budgetboolean required
expires_atstring nullable required
idstring required
is_activeboolean required
is_service_keyboolean required
keystring required
key_namestring nullable required
key_prefixstring nullable required
key_suffixstring nullable required
metadataobject required
reject_user_mismatchboolean nullable required
user_idstring nullable required

Changes

  • fbee488d4d9fRevision changes
    • info

      added the optional property to the response with the status

  • 5125607f1676Revision changes
    • info

      added the new optional request property

    • info

      added the required property to the response with the status