Organisations

Tenant tokens

POST /v1/orgs/{orgId}/tenants/{tenantId}/token, and what a Tenant token can call.

A Tenant token acts as one Tenant. Your backend exchanges its Organisation Key for one, then calls /v1/agents/* with it. Sessions, machines and events are the Tenant's, and the Organisation pays.

Exchange

Exchange an Organisation Key for a Tenant tokencURL

curl -s -X POST "$SAI_API_URL/v1/orgs/$ORG_ID/tenants/$TENANT_ID/token" \
  -H "Authorization: Bearer $SAI_ORG_KEY"

No body.

200 OK · Tenant tokenJSON

{
  "token": "eyJhbGciOiJSUzI1NiIs...",
  "expiresAt": 1790003600000,
  "tenantId": "Xk2p9QzR4tLm8vNa3bCd"
}

The token lasts one hour. expiresAt is Unix time in milliseconds. There is no refresh token: exchange again before it expires. Reuse a token for its hour rather than exchanging for every request.

The caller is the Organisation's own key, or a signed-in owner or admin of the Organisation (the console's Playground does this).

Status	`error`	When
`403`	`session_required`	A personal API key, or any credential other than the two above.
`403`	`not_available_for_tenant`	A Tenant token. A Tenant cannot exchange for itself or another Tenant.
`403`	`tenant_disabled`	The Tenant is disabled.
`403`	`organisation_disabled`	The Organisation is disabled.
`404`	`not_found`	No such Organisation for this key, or no such Tenant in it.
`429`	`rate_limited`	More than 600 exchanges for the Organisation in an hour.
`503`	`unavailable`	Try again shortly.

Use it

Send the token in Authorization, like an API key:

Send a message as the Tenant

curl -s "$SAI_API_URL/v1/agents/message" \
  -H "Authorization: Bearer $TENANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "message": "Open the calendar and read today’s appointments" }'

GET /v1/agents/auth shows who the token acts as:

200 OK · Who the token acts asJSON

{
  "ok": true,
  "userId": "Xk2p9QzR4tLm8vNa3bCd",
  "authType": "firebase",
  "tenantId": "Xk2p9QzR4tLm8vNa3bCd",
  "orgId": "org_3f9a1c0b7e2d4a6f8c10"
}

What a Tenant token can call

Route	Page
`GET /v1/agents/auth`	Authentication
`POST /v1/agents/message`	Message
`GET /v1/agents/events`	Events
`POST /v1/agents/approve`	Approve
`POST /v1/agents/abort`	Abort
`POST /v1/agents/new-session`	New session
`GET /v1/agents/session`, `GET /v1/agents/sessions`, `GET /v1/agents/context`	Sessions
`GET /v1/agents/machines`	Machines
`POST /v1/agents/machines/{machineId}/live`	Live screen
`GET /v1/agents/models`	Models

GET /v1/agents/machines lists the Tenant's enrolled machines. Pass one as machineId on /message.

Every other route answers 403:

403 Forbidden · not_available_for_tenantJSON

{ "error": "not_available_for_tenant", "message": "This route is not available for a Tenant." }

That includes turns, learn, judge, uploads, direct control, the account and keys, and /v1/orgs and /v1/tenants. A Tenant token cannot create or wake a cloud computer.

When a token stops working

A token is checked on every request, not only at the exchange:

Status	`error`	When
`401`		The token has expired. Exchange again.
`401`	`credential_revoked`	The key that exchanged it was revoked, or the member who did is no longer an owner or admin.
`403`	`tenant_disabled`	The Tenant was disabled.
`403`	`organisation_disabled`	The Organisation was disabled.
`404`	`tenant_not_found`	The Tenant was deleted.

A revoked key or a removed member stops its tokens within a minute.