Tool tokens

Issue a workspace tool token (ES256, <= 15 min) for the cell gateway

Creates or reuses the agent session for (workspace, principal, agent_label) and signs a token with claims iss, aud, sub, pty, org, prj, ws, epoch, tools, sid, iat, exp, jti (verify with GET /v1/.well-known/tool-token-keys). tools must be a subset of the API key’s tool permissions (users: of their role). A suspended workspace gets a token too: the cell serves it only the reads of its disk (files read, stat, list and search, X-Served-From: disk) and answers every other call 409 workspace_not_running (wake the workspace; its resume moves the ownership epoch). 409 with the active operation when the workspace is neither running nor suspended; on 409 stale_epoch from the cell, request a new token.

post/v1/workspaces/{workspace_id}/tool-tokens

Request

  • Base URL: https://api.shardflux.dev
  • URL: https://api.shardflux.dev/v1/workspaces/{workspace_id}/tool-tokens
  • Auth: HTTP bearer

Path parameters

workspace_idstring uuid required

UUIDv7, lowercase canonical form.

Request body

agent_labelstring

Attribution label; one agent session per (workspace, principal, label).

toolsstring[]

Response

Default Response

tokenstring required

Compact ES256 JWS; send as Authorization: Bearer to the cell gateway.

token_type'Bearer' required
expires_atstring date-time required

RFC 3339 UTC timestamp with Z.

issued_atstring date-time required

RFC 3339 UTC timestamp with Z.

kidstring required
audiencestring required
workspace_idstring uuid required

UUIDv7, lowercase canonical form.

agent_session_idstring uuid required

UUIDv7, lowercase canonical form.

ownership_epochinteger required
toolsstring[] required
cell_endpointstring required

Changes

No recorded changes to this operation across all 1 revision of this API.