Update an API key
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`).
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/jsonname
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/jsonid
string
REQUIRED
object
string
REQUIRED
Enum:
api_keykind
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_tokenclient_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, expiredexpires_at
string (date-time) | null
REQUIRED
created_at
string (date-time)
REQUIRED
created_by
object
REQUIRED
type
string
REQUIRED
Enum:
user, api_keyid
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": {}}
API Playground
Try this endpoint
PATCH
/v1/keys/{key_id}