---
title: "Issue a workspace tool token (ES256, <= 15 min) for the cell gateway"
method: POST
path: "/v1/workspaces/{workspace_id}/tool-tokens"
tags: ["Tool tokens"]
---

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

`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

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.

## Path parameters

- `workspace_id` string, uuid, required

## Request body

- object
  - `agent_label` string: Attribution label; one agent session per (workspace, principal, label).
  - `tools` string[]

## Response `201`

Default Response

- ToolToken
  - `token` string, required: Compact ES256 JWS; send as `Authorization: Bearer` to the cell gateway.
  - `token_type` 'Bearer', required
  - `expires_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `issued_at` string, date-time, required: RFC 3339 UTC timestamp with Z.
  - `kid` string, required
  - `audience` string, required
  - `workspace_id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `agent_session_id` string, uuid, required: UUIDv7, lowercase canonical form.
  - `ownership_epoch` integer, required
  - `tools` string[], required
  - `cell_endpoint` string, required

## Other responses

- `4XX`: Default Response
- `5XX`: Default Response

---

[API](https://skmtc.dev/shardflux/apis/shardflux-api.md) · [All operations](https://skmtc.dev/shardflux/apis/shardflux-api/llms.txt) · [OpenAPI document](https://skmtc.dev/shardflux/apis/shardflux-api/revisions/ea685f7b39c4?raw)