# Issue a scoped, short-lived agent token for one account

`POST /api/v1/agent-tokens` · operationId `issueAgentToken`

For developers: your server sends this request with a server key; it is not a button in the dashboard.

409 agent_tokens_disabled while agent tokens are off for the Site (Settings); 409 tool_not_approved or tool_not_read_only for a tool that is not reviewed and enabled, or that changes data (writes stay in the page). Retrying issues another token: keep the first answer.

## Authentication

Send `Authorization: Bearer YOUR_SERVER_KEY` (siteServerKey: Site server key in Authorization: Bearer <key> (the scheme is case-insensitive and required; a bare key is 401). Shown once on creation or rotation. Publishable keys cannot authenticate). Keep the server key in server-only configuration; never send it to a browser.

## Request body

Content-Type: application/json (required)

- `accountId` (string, required) · minLength 1, maxLength 512
- `userId` (string | null, optional) · minLength 1, maxLength 512
- `tools` (string[], optional): Reviewed, enabled, read-only tools of this Site.
- `mcpTools` (string[], optional): Tools of your own MCP server this token may call.
- `apiRoutes` (string[], optional): Routes of your own API, as "METHOD /route/template".
- `ttlSeconds` (integer, optional) · minimum 60, maximum 86400

```json
{
  "accountId": "acct_456",
  "userId": "usr_123",
  "mcpTools": [
    "search_docs"
  ],
  "ttlSeconds": 900
}
```

## Responses

- **200**: Success · body `object`
- **400**: bad_request: the request is invalid; message says what to fix and field names the request field · body `Error`
- **401**: unauthorized (missing or invalid server key, missing Bearer scheme) · body `Error`
- **403**: forbidden: the call came from a browser page or another Site; call from your server with this Site’s server key · body `Error`
- **404**: not_found: unknown path, or an ID in the path that is not on this Site · body `Error`
- **409**: agent_tokens_disabled: agent tokens are off for this Site (Settings). tool_not_approved: a tool in tools is not reviewed and enabled. tool_not_read_only: a tool in tools changes data (writes stay in the page). message names the tool. · body `Error`
- **413**: payload_too_large: the request body exceeds 131072 bytes · body `Error`
- **429**: rate_limited: wait for Retry-After · body `Error` · headers `Retry-After`
- **500**: internal_error: fail the protected action; do not retry automatically · body `Error`
- **503**: service_unavailable: temporarily unavailable; only verify retries · body `Error`

### Success body fields

- `token` (string, required) · pattern `^tt_agent_`: Returned once; hand it to the agent. Never log it.
- `tokenId` (string, required)
- `accountId` (string, required)
- `userId` (string | null, required)
- `tools` (string[], required)
- `mcpTools` (string[], optional)
- `apiRoutes` (string[], optional)
- `expiresAt` (number, required): Unix epoch milliseconds.

Failures are not verdicts. Error bodies follow the `Error` schema: `code` is one of `bad_request`, `unauthorized`, `session_reinit_required`, `forbidden`, `not_found`, `conflict`, `identity_required`, `payload_too_large`, `rate_limited`, `internal_error`, `service_unavailable`, `request_failed`, `approval_invalid`, `approval_used`, `approval_expired`, `approval_mismatch`, `step_up_not_held`, `step_up_mismatch`, `step_up_settled`, `step_up_expired`, `step_up_superseded`, `agent_tokens_disabled`, `tool_not_approved`, `tool_not_read_only`. [Errors and retries](/docs/errors) explains each code and what to do.

## Example

```sh tab=curl
curl -sS -X POST 'https://app.trytelltale.dev/api/v1/agent-tokens' \
  -H "Authorization: Bearer $TELLTALE_SERVER_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"accountId":"acct_456","userId":"usr_123","mcpTools":["search_docs"],"ttlSeconds":900}'
```

```js tab=fetch
const response = await fetch("https://app.trytelltale.dev/api/v1/agent-tokens", {
  method: "POST",
  headers: {
    Authorization: 'Bearer ' + process.env.TELLTALE_SERVER_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    "accountId": "acct_456",
    "userId": "usr_123",
    "mcpTools": [
      "search_docs"
    ],
    "ttlSeconds": 900
  }),
  signal: AbortSignal.timeout(5000)
});
const result = await response.json();
```

Machine-readable contract: [openapi.json](https://app.trytelltale.dev/openapi.json). Request builder: the [API explorer](/docs/api-explorer) shows every operation as curl; it sends requests only on a local dashboard.