Create an API key

Creates a key in your project (or `project`, in the same organization). `scopes` and `spend_cap_usd` may not exceed the caller's own, and when the caller expires, `expires_at` must be set and no later than the caller's expiry (`forbidden`, reason `scope_escalation`). The response is the only time `secret` is returned.

POST /v1/keys
Creates a key in your project (or `project`, in the same organization). `scopes` and `spend_cap_usd` may not exceed the caller's own, and when the caller expires, `expires_at` must be set and no later than the caller's expiry (`forbidden`, reason `scope_escalation`). The response is the only time `secret` is returned.

Authentication

Bearer Token (b3os_sk_ API key or b3os_pat_ token) API Key (cookie: __Host-b3os_session)

Header Parameters

Idempotency-Key string optional header
A unique value (for example a UUID) that makes this request safe to retry. Scoped to your project for 24 hours: a retry with the same key, method, path and body returns the stored response with `Idempotent-Replayed: true`, and only to the same API key. Reusing the key for a different request returns `409 idempotency_key_conflict`.

Request Body required

application/json
name string REQUIRED
scopes string[] REQUIRED
Array of: string
project_id string
Defaults to the caller's project.
spend_cap_usd number | null
expires_at string (date-time) | null
metadata object
Up to 16 string key-value pairs you attach to an object for your own use. Keys are 1 to 40 characters of `A-Z a-z 0-9 _ . : -`; values are at most 500 characters. B3OS never interprets them.

Responses

201 The key, with its secret shown once.
application/json
id string REQUIRED
object string REQUIRED
Enum: api_key
kind string REQUIRED
`api_key` (`b3os_sk_…`, made with `POST /v1/keys`) or `cli_token` (`b3os_pat_…`, from the device login; `created_by` is the user who approved it).
Enum: api_key, cli_token
client_id string | null REQUIRED
The device-login client a CLI token was issued to (`b3os-cli`); null for API keys.
name string REQUIRED
redacted string REQUIRED
The start and end of the secret, for recognizing it.
org_id string REQUIRED
project_id string REQUIRED
scopes string[] REQUIRED
Array of: string
spend_cap_usd number | null REQUIRED
spent_usd number REQUIRED
Spend in the current billing period.
status string REQUIRED
Enum: active, revoked, expired
expires_at string (date-time) | null REQUIRED
created_at string (date-time) REQUIRED
created_by object REQUIRED
type string REQUIRED
Enum: user, api_key
id string REQUIRED
last_used_at string (date-time) | null REQUIRED
revoked_at string (date-time) | null REQUIRED
metadata object REQUIRED
Up to 16 string key-value pairs you attach to an object for your own use. Keys are 1 to 40 characters of `A-Z a-z 0-9 _ . : -`; values are at most 500 characters. B3OS never interprets them.
secret string REQUIRED
400 The request failed validation (`invalid_request`, `invalid_url`).
401 Missing, malformed, expired or revoked credentials (`unauthorized`).
403 Authenticated but not allowed (`forbidden`, `egress_denied`).
404 No such project in your organization (`project_not_found`).
409 The object's state does not allow this operation, or the idempotency key conflicts.
413 The request body exceeds this operation's limit.
415 The Content-Type is not accepted by this operation.
429 A rate, concurrency or quota limit applies (`rate_limited`, `concurrency_limited`, `quota_exceeded`).
500 Something failed inside B3OS (`internal`). Retry with backoff.
503 The node or the product is not available right now (`node_unavailable`, `product_unavailable`, `capacity_unavailable`). 
curl -X POST 'https://beta-api.b3os.org/v1/keys' \  -H 'Authorization: Bearer YOUR_API_TOKEN' \  -H 'Content-Type: application/json' \  -d '{  "name": "research agent",  "scopes": [    "vision:run",    "sandboxes:write",    "sandboxes:run",    "infer:run"  ],  "spend_cap_usd": 20,  "expires_at": "2026-12-31T00:00:00.000Z"}'
const response = await fetch('https://beta-api.b3os.org/v1/keys', {  method: 'POST',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN",      "Content-Type": "application/json"  },  body: JSON.stringify({    "name": "research agent",    "scopes": [      "vision:run",      "sandboxes:write",      "sandboxes:run",      "infer:run"    ],    "spend_cap_usd": 20,    "expires_at": "2026-12-31T00:00:00.000Z"  })});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.post('https://beta-api.b3os.org/v1/keys', headers=headers, json={  "name": "research agent",  "scopes": [    "vision:run",    "sandboxes:write",    "sandboxes:run",    "infer:run"  ],  "spend_cap_usd": 20,  "expires_at": "2026-12-31T00:00:00.000Z"})print(response.json())
201 Response 
{  "id": "key_01m5t5csy2wt4e3er052chyf1x",  "object": "api_key",  "kind": "api_key",  "client_id": null,  "name": "research agent",  "redacted": "b3os_sk_ex4m…2321",  "org_id": "org_01m5t5hthd29mm5wpza5ndd6mm",  "project_id": "prj_01m5t3pf8heewxt65ej3dm577y",  "scopes": [    "vision:run",    "sandboxes:write",    "sandboxes:run",    "infer:run"  ],  "spend_cap_usd": 20,  "spent_usd": 0,  "status": "active",  "expires_at": "2026-12-31T00:00:00.000Z",  "created_at": "2026-10-25T21:00:00.000Z",  "created_by": {    "type": "user",    "id": "usr_01m5t3jv4b5sappg7vzv1rwx6x"  },  "last_used_at": null,  "revoked_at": null,  "metadata": {},  "secret": "b3os_sk_ex4mple7ex4mple7ex4mple7ex4mple7_957a2321"}
Previous List API keys
Next Describe the calling credential
Ask a question... ⌘I