DocsAuthentication

Get started · 2 of 4

Authentication

Every request carries a project API key as a bearer token. Keys are created, rotated and revoked in the app; the API has no endpoints for managing them.

Sending the key

Send the key in the Authorization header with the scheme Bearer. The samples read it from an environment variable, OXUMI_API_KEY.

Header
Authorization: Bearer ox_live_…

A request with no header, another scheme, an unknown key, an expired key or a revoked key gets the same 401. The body does not say which it was.

GET /v1/agentscURL
curl --fail-with-body "http://localhost:4000/v1/agents" \  -H "Authorization: Bearer $OXUMI_API_KEY"
401Without a valid keyCaptured
{  "message": "Missing or invalid API key. Send it as: Authorization: Bearer <key>",  "error": "Unauthorized",  "statusCode": 401}

API keys

Create a key on a project's API page: open your projects, choose a project, then API → API keys. Copy it straight away; it is displayed only at that moment.

A key without an expiry works until it is rotated or revoked. A working key is one that is active or expiring.

A key
Format
ox_live_ followed by 43 characters
Shown
Once, when it is created
Stored
As a hash; it cannot be shown again
Listed as
Its first 16 characters, e.g. ox_live_a0P82HHa…
Scope
One project: its agents and its calls
Expiry
Optional, 1 to 3,650 days from creation
Limit
20 working keys per project

Key statuses

The app shows one of four statuses for each key. Only the first two are accepted by the API.

Status → accepted?
active
Yes. In normal use.
expiring
Yes. Rotated; works until its grace period ends.
expired
No. Its expiry time has passed.
revoked
No. Switched off by hand; cannot be undone.

Rotating a key

Rotating issues a replacement and keeps the old key working for a grace period, so a live integration can be switched over without downtime.

  • If the old key was already due to expire sooner than the grace period, the earlier time stands.
  • Revoking is different: the key stops working immediately and there is no replacement.
Rotation
Grace period
24 hours unless you choose otherwise
Range
0 to 168 hours. 0 stops the old key at once.
Old key
expiring during the grace period, then expired
New key
Same name, no expiry
Allowed for
Active keys only

Keep keys on your server

  • Read the key from configuration or a secret store, never from source code.
  • Never put a key in a web page or a mobile app. Anyone holding it can place calls from your project.
  • Use one key per system that connects. The app shows when each key was last used and how many requests it made.

Note · Browsers cannot call the API

The API answers cross-origin requests only from the Oxumi app itself. Call it from your back end.

Set the key for the samples
export OXUMI_API_KEY="ox_live_…"