Skip to main content

API Keys

Manage your API keys for programmatic access to the platform.

API keys are user-owned: each key belongs to the user who created it. You only see and manage the keys you created; teammates in the same organization manage their own keys separately.

Key List​

View all your API keys with:

ColumnDescription
NameDescriptive key name
Key PreviewKey identifier (sk-proj-xxxx...xxxx)
TypeInference or Management
API ScopesEnabled API scopes for the key
CreatedCreation date
ExpiresExpiration date (if set)
Last UsedMost recent usage
Usage CountNumber of times the key has been used
StatusActive or Expired

List controls​

The key list has controls to help you manage many keys:

  • Type filter shows All, Inference, or Management keys.
  • Column show / hide toggles which columns are visible, so you can focus on what you care about.
  • Row density switches between comfortable and compact rows.
  • Restriction badges: keys with constraints show badges (models / IPs / spend). Click a badge to reveal the exact allowlist or cap applied to that key, so you can audit restrictions without opening each key.
  • Analytics: every row has an Analytics action that opens the full traffic picture for that one key. See Key Analytics.

Creating a Key​

  1. Click Create key
  2. Enter a Name (e.g., "Production Backend")
  3. Choose what the key is for under What is this key for? (see Key purposes)
  4. For a knowledge key, pick its knowledge bases under Knowledge base access (see Knowledge base access)
  5. Optionally set an expiry (see Expiry options)
  6. Optionally expand Advanced settings to change the API scopes or apply constraints (see Constraints)
  7. Confirm
  8. Copy the key immediately

The new key is revealed once, under the heading "Your New API Key": "This key won't be shown again. Please save it in a secure location."

warning

The full API key is only shown once. Copy and store it securely before closing the dialog.

Expiry options​

OptionEffect
30 daysExpires 30 days from creation
90 daysExpires 90 days from creation
1 yearExpires one year from creation
Custom date"Pick any future date. The key stops working at 00:00 UTC on that day."
Never expiresNo expiry; rotate it on your own schedule

Key purposes​

The purpose sets the key type, its API scopes and, for knowledge, its knowledge base access in one choice:

PurposeKey typeAPI scopes
Knowledge app (search + chat)Inferenceinference:chat and knowledge:read, limited to the knowledge bases you pick (Only selected; pick at least one)
InferenceInferenceThe inference key's default set (model calls and your own async jobs)
ManagementManagementThe management key's default set (usage, billing and limits automation)

Knowledge app is offered, and is the starting choice, only while knowledge bases are available to your organization; otherwise the form starts on Inference. It never carries a write scope: knowledge:write (upload and manage documents) is an explicit tick under Advanced settings, available to admins and owners. A knowledge app key is limited to a list of knowledge bases, so it cannot create knowledge bases or read the organization-wide knowledge usage; see Knowledge base access. The individual scopes stay editable under Advanced settings; once you change them the form says "Scopes changed under Advanced settings."

Scope defaults​

If you leave the scope selection untouched, the key is created with the scopes of its purpose: the full default set of its key type for Inference and Management, exactly inference:chat and knowledge:read for Knowledge app. An empty scope list is rejected, since a key must keep at least one scope.

Key Types and API Scopes​

Choose the narrowest type and API scope set that fits the integration.

Inference Keys​

Inference keys are for model calls and OpenAI-compatible SDK usage.

API ScopeAccess
inference:chatChat completions
inference:completionsText completions
inference:embeddingsEmbeddings
inference:imagesImage generation
inference:audioThe whole audio family: transcription, translation, speech synthesis, and the realtime transcription WebSocket
models:listModel listing
models:retrieveSingle model metadata
jobs:stats_ownRead your own async job statistics
jobs:read_ownRead your own async jobs
jobs:cancel_ownCancel your own async jobs
knowledge:readKnowledge bases: list, search, download originals, chunk previews, usage summaries, answer feedback; with inference:chat, chat with knowledge bases. Portal label Knowledge: read & search
knowledge:writeEverything knowledge:read allows, plus create and delete knowledge bases, upload and change documents, and exports. Portal label Knowledge: manage

The two knowledge scopes are offered only when knowledge bases are enabled on your platform. They are never part of the default scope set or of any older scope name, so existing keys do not gain knowledge access; tick them explicitly. See Knowledge base access.

Async jobs are submitted through inference endpoints by setting the background/async request option. Direct POST /api/v1/jobs and DELETE /api/v1/jobs/{job_id} are not public API-key operations.

Management Keys​

Management keys are for public portal automation. They cannot call inference endpoints.

API ScopeAccess
usage:read_currentCurrent usage
usage:read_historyUsage history
usage:read_summaryUsage summary
usage:read_reportUsage report export data
usage:read_breakdownPer-user tenant usage breakdown (admin/owner only)
billing:read_currentWallet and commitment (admin/owner only), plus current plan (any user)
billing:read_cyclesRetired name. Grants what billing:read_invoices grants
billing:read_invoicesBilling statements and transactions (admin/owner only)
billing:read_summaryRetired name. Grants what billing:read_current grants
profile:readCurrent profile
rate_limits:readCurrent rate limits
budgets:read_ownRead your own spend limit and the PAYG spend cap
budgets:update_ownUpdate or clear your own spend limit; update or clear the PAYG spend cap (admin/owner only)

Public API keys do not create, update, or delete API keys. Use the portal session for key management.

Management Scope Details​

API ScopeWhat it returns
usage:read_currentCurrent-month usage summary with request, token, model, duration, and cost totals. Defaults to the key owner's personal usage.
usage:read_historyIndividual usage events with optional date, model, endpoint, API key, limit, and offset filters. Every event carries the api_key_id that produced it. Defaults to the key owner's personal usage.
usage:read_summaryAggregated usage summary for a required start_date/end_date range. Defaults to the key owner's personal usage.
usage:read_reportTime-series usage report for a required date range, grouped hourly, daily, weekly, or monthly. Also grants the per-key analytics endpoint. Defaults to the key owner's personal usage.
usage:read_breakdownPer-user tenant usage breakdown. This endpoint requires the key owner to be a tenant admin or owner, so the portal only offers this scope to those roles.
billing:read_currentYour wallet balance and its credit lots, your commitment contract if you have one, and your current plan status for the open period. The wallet and commitment reads require the key owner to be a tenant admin or owner; the plan read is open to any user in the tenant.
billing:read_cyclesRetired name, kept working. Billing cycles were withdrawn as a concept, so this scope now grants exactly what billing:read_invoices grants. A key that already carries billing:read_invoices gains nothing from it.
billing:read_invoicesIssued invoice documents, the transactions recorded against one invoice, and the tenant's transaction feed. Includes invoice line items, totals, due date, paid date, and payment status. Requires the key owner to be a tenant admin or owner.
billing:read_summaryRetired name, kept working. It now grants exactly what billing:read_current grants.
profile:readThe key owner's current public profile.
rate_limits:readThe current effective rate limits for the key owner/tenant.
budgets:read_ownThe key owner's personal daily spend limit, and the tenant's pay-as-you-go spend cap.
budgets:update_ownUpdates or clears the key owner's personal daily spend limit, and the tenant's pay-as-you-go spend cap. Changing the PAYG spend cap requires the key owner to be a tenant admin or owner; changing the personal limit does not.

Integration Scopes​

The platform integrations (webhooks, domains, connections) have their own scopes. Reading works on both key types; creating and managing needs a management key.

API ScopeAccessKey type
webhooks:readList webhook endpoints, deliveries and event typesInference or management
webhooks:writeEverything webhooks:read allows, plus add, change, delete, test, redeliver and rotate secretsManagement only
domains:readList domains and their verification stateInference or management
domains:writeEverything domains:read allows, plus add, check and delete domainsManagement only
connections:readList connections (connections are not available yet)Inference or management
connections:writeAdd, check, change and delete connections (not available yet)Management only
  • Only an organization owner or admin can add these scopes to a key. They are never part of a default scope set or of an older scope name: ask for them explicitly.
  • A *:write scope asked for on an inference key is refused when the key is created or changed (422), and a *:write scope on an inference key never grants anything (403 scope_missing).
  • An inference key with knowledge:write can still use a verified domain in a knowledge source: using an integration needs no integration scope.
  • A key limited to a list of knowledge bases cannot use the webhook routes (403 kb_not_in_allowlist).
  • knowledge:connections no longer exists. Asking for it when a key is created or changed is refused with 422 (unknown scope); use connections:read.

Constraints​

You can lock down how an API key is allowed to be used at creation time, and update those constraints later. Advanced settings on the create form holds three controls.

ConstraintWhat it does
Model allowlistRestrict an inference key to selected active models. Requests for any other model are rejected with 403 Forbidden. Leaving every model unchecked grants access to every active model the user is otherwise allowed to use.
IP allowlistRestrict requests to one or more source IP addresses (CIDR ranges supported). Requests from any other IP are rejected with 403 Forbidden. Empty list = no IP restriction.
Daily spend cap (USD)"Requests stop when this key reaches its daily spend cap." Capped per UTC day; the pre-request check returns 429 Too Many Requests once the cap is hit, and the counter resets at the start of the next UTC day.

A key's daily spend cap is separate from your personal daily limit and your organization's, and it stacks with both. See Cost Limits for how the layers resolve.

Constraints are enforced by the gateway. Setting a field to empty (or sending null via the API) clears that constraint.

Use scope constraints to limit blast radius if a key is leaked: a key scoped to a single model, a single egress IP, and a $10/day cap is much less dangerous than an unscoped one.

Knowledge base access​

When a knowledge scope is ticked, the form shows Knowledge base access with three choices, stored as the key's kb_allowlist:

Choicekb_allowlistEffect
All knowledge basesnullEvery knowledge base of the organization, including ones created later. The form warns: "This key can read every knowledge base of your organization, including ones created later. Choose “Only selected” to limit it."
None[]The key keeps its scope but cannot access any knowledge base; every knowledge route answers 403 kb_not_in_allowlist except GET /v1/knowledge_module.
Only selectedlist of 1–100 idsOnly these knowledge bases.

Only a key with All knowledge bases can create a knowledge base: a key with Only selected or None gets 403 kb_not_in_allowlist on POST /v1/knowledge_bases (and on the organization-wide GET /v1/knowledge_usage). Create knowledge bases with an unrestricted key or in the portal, then add them to the restricted key's list. A request that names any knowledge base outside the list is refused as a whole with 403 kb_not_in_allowlist. The key table shows a badge (All knowledge bases, No knowledge bases or N knowledge bases). On PATCH /api/v1/api-keys/{key_id}, omitting kb_allowlist leaves it unchanged; null means all and [] means none. See the Knowledge Bases Quickstart.

Update a constraint via API​

curl -X PATCH https://api.infus.ai/api/v1/api-keys/{key_id} \
-H "Authorization: Bearer YOUR_JWT_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"model_allowlist": ["your-chat-model"],
"ip_allowlist": ["203.0.113.10/32"],
"spend_cap_usd": 10.00
}'

Send null for any field to clear it. Scope changes are recorded as api_key_scope_updated audit events. See the Security section of your profile for account security information.

Naming Best Practices​

Use descriptive names that include:

  • Environment (Production, Staging, Development)
  • Application name
  • Purpose

Examples:

  • Production - Main Backend
  • Staging - Testing
  • Development - Local

Key Security​

Storage​

  • Do: Use environment variables
  • Do: Use secrets managers (AWS Secrets, Vault)
  • Don't: Commit to version control
  • Don't: Share in plaintext

Rotation​

Rotate keys regularly:

  1. Create a new key
  2. Update your applications
  3. Verify new key works
  4. Delete the old key

Operator visibility​

Your platform operator can list your organization's API key metadata and revoke a key. What they see is the key's name, its preview prefix, type, scopes, restrictions, and its creation and last-used timestamps.

The secret itself is never visible to them. Only a hash of it is stored, so there is no path, for an operator or anyone else, that returns a usable key after creation.

If a key stops working unexpectedly and it has not expired, ask your platform administrator whether it was revoked.

Key Actions​

Copying the Key​

The full key can only be copied from the success banner shown immediately after creation. Key rows do not have a copy action; the list shows the key preview (sk-proj-xxxx...xxxx) for identifying keys in logs and debugging.

Delete Key​

  1. Click the trash icon
  2. Confirm deletion
  3. Key is immediately revoked
danger

Deletion is immediate and irreversible. Any applications using this key will stop working.

Key Analytics​

The Analytics action on a key row opens a page for that credential alone. A key's row tells you how many requests it has made; this page tells you what it has been doing.

It is the Usage page scoped to one key, and deliberately so — the same board, the same numbers, narrowed:

  • the same eight headline tiles, each with a delta pill comparing the selected range against the immediately preceding period of equal length
  • the same range pills and the same Custom range picker
  • the same Focus / Board / Overlay trend layouts over the same four measures: Requests, Tokens, Input tokens, Output tokens
  • the Token distribution and Performance & cache insight cards
  • the Usage by Model table
  • Recent Activity, capped at 10 rows, with a Status column

The Status column is derived from whether the request succeeded and, where it failed, from the platform error code it returned. It is not an HTTP status code, and a failure that carries no error code simply reads Failed.

No money on this screen

Like Usage, this page reports volume only: no cost tile, no cost column, no per-model cost. Amounts live on Billing.

A few Usage controls have no counterpart here: there are no p50/p95 percentiles, no per-model filter and no export.

Performance figures need a range of 31 days or less

The latency, cache and throughput rows are computed from individual request records, which are only read for ranges up to 31 days. On a longer range those rows render as em dashes with a caption saying why, while every figure derived from totals stays populated. Shorten the range to get them back.

Daily buckets follow your timezone

Daily, weekly and monthly points are cut on your local day boundaries, including across daylight-saving transitions, so a request made just before local midnight is charted on the day you made it. Hourly granularity stays on UTC hours — an hour is an hour. The Usage page behaves the same way.

Who can see which key​

Analytics are always scoped to your own organization.

  • Owners and admins can open the analytics of any key in the organization.
  • Members can open only their own keys.

A key id that does not exist, or that belongs to another organization, returns an empty report — every figure zero — rather than an error. The screen cannot be used to discover whether a key id exists.

Key Limits​

LimitValue
Max keys per userSet by your organization's tenant quota (platform default: 10; unlimited if configured so)
Key name length2–255 characters
Key expirationOptional; must be a future date. The "1 year" option is a UI preset, not an enforced maximum

Expiry Warnings​

Keys that expire within the next 7 days display a small warning badge next to the expiry date showing the actual remaining days, for example 1 day, 3 days, or 7 days. This gives you a clear signal to rotate a key before it stops working.

Keys expiring in more than 7 days show no badge, just the expiry date.

Expired Keys​

Expired keys are:

  • Shown with "Expired" status
  • Unable to make API calls
  • Kept in the list until you delete them manually

API Reference​

Manage API keys programmatically with a JWT access token from login. Public API keys cannot manage API keys.

List Your API Keys​

curl https://api.infus.ai/api/v1/api-keys \
-H "Authorization: Bearer YOUR_JWT_ACCESS_TOKEN"

Response:

{
"data": [
{
"id": "uuid",
"name": "Production Backend",
"key_type": "inference",
"key_preview": "sk-proj-PEyx...b01a",
"scopes": ["inference:chat", "models:list"],
"created_at": "2024-01-15T10:00:00Z",
"expires_at": "2024-07-15T10:00:00Z",
"last_used_at": "2024-01-20T15:30:00Z",
"usage_count": 40,
"is_active": true
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"total_pages": 1,
"has_next": false,
"has_prev": false
}
}

Create API Key​

curl -X POST https://api.infus.ai/api/v1/api-keys \
-H "Authorization: Bearer YOUR_JWT_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Production Backend",
"key_type": "inference",
"scopes": ["inference:chat", "models:list"],
"expires_at": "2024-12-31T23:59:59Z"
}'

Request Parameters​

ParameterTypeRequiredDescription
namestringYesDescriptive name (2–255 chars)
key_typestringNoinference or management; defaults to inference
scopesstring[]NoAPI scope list for the selected key type. Omit it to receive the full default set for that type; an empty list is rejected
expires_atdatetimeNoISO 8601 expiration date (must be in the future)

Response (201 Created):

{
"id": "uuid",
"name": "Production Backend",
"key_type": "inference",
"key": "sk-proj-abc123xyz789...",
"scopes": ["inference:chat", "models:list"],
"created_at": "2024-01-15T10:00:00Z",
"expires_at": "2024-12-31T23:59:59Z"
}
warning

The key field contains the full API key and is only returned once at creation time. Store it securely.

Delete API Key​

curl -X DELETE https://api.infus.ai/api/v1/api-keys/{key_id} \
-H "Authorization: Bearer YOUR_JWT_ACCESS_TOKEN"

Response: 204 No Content

Reading Analytics Programmatically​

curl "https://api.infus.ai/api/v1/usage/api-keys/{key_id}/analytics?granularity=daily&start_date=2026-07-01&end_date=2026-07-31" \
-H "Authorization: Bearer YOUR_JWT_ACCESS_TOKEN"

This endpoint is also reachable with an API key that carries usage:read_report. A key created from the legacy usage:read grouping already has it, so no key needs re-issuing.

Query Parameters​

ParameterValuesDescription
granularityhourly, daily, weeklyBucket size for the time series. It also caps how wide the range may be: 7 days hourly, 90 days daily, 365 days weekly
model_namemodel identifierOptional. Narrows the totals and the time series to one model. The per-model breakdown stays unfiltered, so it can still populate a model selector

The response carries the resolved range, totals for it, previous_totals for the immediately preceding window of equal length, the time series, a per-model breakdown, and a performance block with p50/p95 latency, cache counters and tokens per second.

Two behaviours are worth coding against:

  • The series is dense. Buckets with no traffic are returned as zeros rather than omitted, so you can plot the array as-is without filling gaps yourself.
  • performance is optional. For a range longer than 31 days it reports available: false with null fields; every other block is still populated.

The same authorization rules as the portal apply: the read is scoped to your organization, owners and admins may read any key in it, other roles only their own, and an unknown or out-of-organization key id answers with an all-zero report instead of a 404.

Python Example​

import requests
from datetime import datetime, timedelta

jwt_token = "YOUR_JWT_ACCESS_TOKEN"
base_url = "https://api.infus.ai"
headers = {"Authorization": f"Bearer {jwt_token}"}

# List keys
response = requests.get(f"{base_url}/api/v1/api-keys", headers=headers)
result = response.json()
keys = result["data"]
print(f"You have {result['pagination']['total']} API keys")

# Create key with 6-month expiration
expires = (datetime.utcnow() + timedelta(days=180)).isoformat() + "Z"
response = requests.post(
f"{base_url}/api/v1/api-keys",
headers={**headers, "Content-Type": "application/json"},
json={
"name": "New Production Key",
"key_type": "inference",
"scopes": ["inference:chat", "models:list"],
"expires_at": expires,
}
)
new_key = response.json()
print(f"New key created: {new_key['name']}")
print(f"Full key (save this!): {new_key['key']}")

# Delete key
key_id = keys[0]["id"]
requests.delete(f"{base_url}/api/v1/api-keys/{key_id}", headers=headers)

API Key Access Scope​

Inference keys work with /v1/* OpenAI-compatible endpoints and the matching /api/v1/* direct HTTP endpoints. Management keys work only with the public management endpoints listed above. Organization, member, tenant-admin, admin portal, and API-key management endpoints require a JWT session.

Troubleshooting​

Key Not Working​

  1. Check if key is expired
  2. Verify key is copied correctly (no extra spaces)
  3. Ensure Bearer prefix in Authorization header
  4. Check rate limits

Can't Create Keys​

  • You may have reached the maximum key limit
  • Your account role may not allow key creation
  • Contact your organization admin