API Keys and Workspaces

Choose the scope and credential first

• One key's usage/budget: call GET /v1/key with that inference API key. Read usage, limit_remaining, and limit_reset. This is a key spending budget, not the enterprise wallet or credit balance.
• Enterprise wallet and credit: call GET /enterprise/v1/billing/balance with a MANAGEMENT key scoped only to tenant:billing:read. Inference and PROVISIONING keys cannot use it.
• Account charges/request reconciliation: existing GET /v1/billing and GET /v1/billing/requests/{request_id} use an inference key or signed-in JWT. Management keys cannot call these /v1 endpoints. Recorded charges and remaining balance are different metrics.
• Legacy account balance: GET /v1/billing/balance remains compatible and reports account funds, not the calling key's remaining budget. Prefer the Enterprise endpoint for new enterprise balance monitoring.

Enterprise API guide · Get enterprise balance

API keys authenticate inference requests. Workspaces label keys by project or environment so usage and audit trails remain understandable as a team grows.

Recommended workspace layout

Create separate workspaces for operational boundaries such as:

• development
• staging
• production
• a customer, product, or internal team with separate ownership

Use a separate key for each deployed service. Do not share one production key across unrelated applications.

Create a key

From API Keys in the console:

1. Select or create a workspace.
2. Enter a descriptive key name.
3. Optionally set an expiration time.
4. Optionally set a spend limit and reset period.
5. For eligible enterprise accounts, optionally add allowed IP addresses or CIDR ranges.
6. Create and securely store the secret.

The API key management endpoints support programmatic creation and lifecycle management. Keep management credentials and inference credentials separated in your own systems.

Spend limits

A key can have a lifetime limit or a limit that resets daily, weekly, or monthly. A reset period requires a spend limit. The key limit is evaluated together with account balance, credit, and account-level spend protection; a permissive key cannot override a stricter account control.

IP restrictions

An API-key IP allowlist limits one key. An enterprise tenant IP policy can apply to every key in the tenant. When both exist, the request must satisfy all applicable restrictions.

Use explicit public IPs or CIDR ranges. Before enabling a restrictive policy, include every production egress address and verify traffic with a non-critical key.

Key lifecycle

• Active — accepted when all other checks pass.
• Disabled — temporarily blocked and can be re-enabled.
• Expired — no longer accepted after its configured expiry.
• Deleted — permanently removed.

Rotation without downtime

1. Create a replacement key with the same required workspace and policies.
2. Deploy it to your secret manager and application.
3. Confirm successful production traffic on the new key.
4. Disable the old key and watch for unexpected callers.
5. Delete the old key after the observation window.

Never commit a key to source control, put it in browser code, or paste it into a ticket or chat.

If a key is exposed

1. Disable or delete it immediately.
2. Create and deploy a replacement.
3. Review key activity, request logs, and spend for unauthorized use.
4. Check source history, CI logs, browser bundles, and third-party systems for additional copies.
5. Contact support with the key display identifier, not the full secret.

Enterprise administration

Enterprise administrators can audit key metadata and ownership across the tenant and revoke keys without viewing plaintext secrets. Member model access, tenant IP policy, and data residency can further constrain what a valid key is allowed to do.