Docs — API Reference/docs/api-reference/authentication

Authentication

Every request carries a bearer key in the Authorization header. Keys are project-scoped and carry explicit scope lists checked by the trust kernel at execution time. These endpoints manage keys and mint short-lived session tokens for client surfaces.

Open in playground Runs resource

[ 01 ]post — /v1/keys

POST/v1/keys

Create an API key with exactly the scopes listed. The secret is returned once, on this response only.

param	type	req	description
name	string	required	Human label, e.g. the service that will hold the key.
scopes	string[]	required	Scope list, e.g. ["runs:write", "context:documents"]. No wildcards.
expires_at	string	optional	ISO 8601 expiry. Omit for non-expiring; Enterprise policies may require one.

[ request ]POST

{
  "name": "billing-worker",
  "scopes": ["runs:write", "runs:read", "context:finance"],
  "expires_at": "2026-12-31T00:00:00Z"
}

[ response ]200 ok

{
  "id": "key_7d20fa11",
  "object": "api_key",
  "name": "billing-worker",
  "secret": "sk_live_…shown_once…",
  "scopes": ["runs:write", "runs:read", "context:finance"],
  "expires_at": "2026-12-31T00:00:00Z"
}

[ 02 ]post — /v1/sessions

POST/v1/sessions

Mint a 15-minute session token for a browser or mobile client, scoped to one end user's slice of the graph.

param	type	req	description
user_id	string	required	Your stable identifier for the end user.
scopes	string[]	optional	Subset of the parent key's scopes. Defaults to read-only.

[ request ]POST

{
  "user_id": "u_82731",
  "scopes": ["runs:read"]
}

[ response ]200 ok

{
  "object": "session",
  "token": "st_…",
  "expires_at": "2026-06-11T08:15:00Z",
  "scopes": ["runs:read"]
}

[ 03 ]delete — /v1/keys/:id

DELETE/v1/keys/:id

Revoke a key. Propagates globally in under five seconds; in-flight runs complete.

param	type	req	description
id	string	required	Key identifier. Path parameter.

[ response ]200 ok

{
  "id": "key_7d20fa11",
  "object": "api_key",
  "revoked": true
}

More resources

[next]Models2 endpoints