Quickstart

Follow the Authentication Guide to sign in, then open the Management Keys page and create a management key. Store it separately from standard application keys. Send it as a bearer token only to Platform Management endpoints.

A standard API key cannot call key or guardrail management endpoints. A valid management key can still receive 403 Forbidden when its owner no longer has the required account role.

Use GET /api/v1/keys to inspect keys visible to the management key’s account:

Use returned public identifiers for later retrieve, update, revoke, or guardrail-assignment requests. Never infer access from a key name or masked token.

Create an application key with POST /api/v1/keys. The full secret is returned only in the create response, so persist it in your secret manager before discarding that response. Rotation should create a replacement, deploy it to the application, verify traffic, and then revoke the old key.

credit_limit_windows accepts any combination of 1h, 1d, and 7d rolling spending caps. If any configured window is exhausted, calls with that key return 429 Too Many Requests until usage leaves the window. Send an empty object when updating a key to clear all rolling caps.

When a create request omits all spending-limit fields and guardrail_id, the new key uses the workspace Governance Defaults. Explicit limits, rolling windows, or a guardrail replace that default choice. Send credit_limit_cents: null to create an unlimited native limit. A supplied amount without a reset interval remains a lifetime limit. Updates never reapply workspace defaults, and changing defaults does not change existing keys.

Create and update accept tags, an array of full key:value strings. List, retrieve, create and update responses return that complete array. A PATCH replaces the array; omitting tags preserves it. The key must be 1–32 characters and the value 1–64, with exactly one colon and no whitespace. At most 20 distinct tags are allowed, including the presets. Invalid formats or conflicting presets return 422 with tag validation errors; a non-array or non-string element returns 400.

Exactly one purpose tag is required: usage:developer or usage:service. Management API creation adds usage:service when no purpose is supplied, including tags: []. Dashboard creation and tag updates without a purpose use usage:developer. Existing keys are migrated as Developer. Environment is optional and accepts at most one of env:production, env:staging, or env:dev (env:prod is not accepted).

Dashboard create/edit offers purpose and environment shortcuts plus custom tags and suggestions from kept standard keys in the current workspace only. Lists display values with the complete tag on hover. Tags do not change key ownership, visibility, or permissions. Tags can associate a key with a shared tag budget.

Workspace administrators set a member’s required tags in Team, through the member budget form. Required tags are case-sensitive custom tags such as team:growth. The usage: and env: namespaces are reserved. A member can have at most 19 required tags, and each key still has a limit of 20 tags in total.

Every new standard key automatically includes its owner’s required tags in that workspace. Creation combines submitted tags with the required tags before validation. For example, if the member requires team:growth, a Management API create request with tags: ["project:chatbot"] returns project:chatbot, team:growth, and the default usage:service.

A PATCH that supplies tags must retain every required tag. Removing a required tag returns 422 with a validation error naming the missing tags, even when the caller is an administrator. Omitting tags preserves the key’s tags. Members can still add or remove ordinary tags.

To remove a required tag, an administrator changes the member’s configuration in Team. Saving the configuration adds new required tags to all of that member’s existing standard keys and removes revoked required tags. Other tags remain unchanged. This includes disabled and expired keys, but excludes deleted keys. If any key cannot accept the final tag set, the entire save fails and the form identifies the key to fix.

Tag budgets use each key’s current tags. Changing required tags also changes the budget attribution of existing spending in the current period. Adding a required tag can immediately exhaust that tag’s budget. Existing members start with no required tags, and their keys remain unchanged until an administrator saves a configuration.

Guardrails are reusable account policies for model, provider, and spending controls. Manage policies through /api/v1/guardrails, then use /api/v1/guardrail_assignments to attach or remove them. Treat a rejected assignment as a policy or ownership failure instead of silently continuing without the guardrail.

Create a positive block-mode guardrail, then assign its guardrail_id and a case-sensitive tag such as dept:ml. Choose exactly one target, api_token_id, account_user_id, or tag. Tag pools require an administrator. Disabled pools do not enforce limits. Management requests do not consume budget.

Pools aggregate current standard-key tags, including spend from deleted, disabled, and expired keys. Adding or removing a tag moves that key’s current-period spend. Creating or recreating a pool never resets spend. Key counts exclude deleted keys. Every matching pool must allow a request; rejection returns 403 and the tag name.

A null credit_limit_reset_interval means lifetime. Other periods use UTC. The alert threshold defaults to 80 and accepts 1 through 100. Direct guardrail updates affect all assignments; dashboard tag-budget edits copy the policy first.

Admission checks reservations. Settlement can exceed them, show usage above 100%, and block subsequent paid requests. Logs use log creation time; pending tasks and batches use their creation time. Tasks accepted in an earlier period may settle in a later one.