PATCH /v1/keys/{key_id}
Renames a key or changes its spend cap, expiry or metadata. Scopes cannot change; create a new key instead. A caller with a spend cap or an expiry cannot set a larger cap or a later (or no) expiry than its own (`forbidden`, reason `scope_escalation`).

Authentication

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

Path Parameters

key_id string required path
Example: "key_01m5t5csy2wt4e3er052chyf1x"

Request Body required

application/json
name string
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

200 The updated key.
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.
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 key in your organization (`api_key_not_found`).
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 PATCH 'https://beta-api.b3os.org/v1/keys/key_01m5t5csy2wt4e3er052chyf1x' \  -H 'Authorization: Bearer YOUR_API_TOKEN' \  -H 'Content-Type: application/json' \  -d '{  "spend_cap_usd": 50}'
const response = await fetch('https://beta-api.b3os.org/v1/keys/key_01m5t5csy2wt4e3er052chyf1x', {  method: 'PATCH',  headers: {      "Authorization": "Bearer YOUR_API_TOKEN",      "Content-Type": "application/json"  },  body: JSON.stringify({    "spend_cap_usd": 50  })});const data = await response.json();console.log(data);
import requestsheaders = {    'Authorization': 'Bearer YOUR_API_TOKEN'}response = requests.patch('https://beta-api.b3os.org/v1/keys/key_01m5t5csy2wt4e3er052chyf1x', headers=headers, json={  "spend_cap_usd": 50})print(response.json())
200 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": 50,  "spent_usd": 1.42,  "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": "2026-10-25T21:30:00.000Z",  "revoked_at": null,  "metadata": {}}
Ask a question... ⌘I