---
title: "Exchange a headless turn's resume grant for a fresh MCP token"
method: POST
path: "/v1/headless/resume-token"
tags: ["Internal"]
---

# Exchange a headless turn's resume grant for a fresh MCP token

`POST /v1/headless/resume-token`

## Request

- Base URL: `https://api.openworklabs.com`
- URL: `https://api.openworklabs.com/v1/headless/resume-token`
- Auth: HTTP bearer

For the headless runner only, with `Authorization: Bearer $DEN_HEADLESS_RUNNER_CALLBACK_TOKEN`. Body `{ grant, sessionId, messageId }`. Exchanges the resume grant Den minted with a turn for a fresh member-scoped MCP token (at most an hour, same read-only setting) for that turn, its background tasks and their reports, while the member is still active and `headlessDurableTurns` is on. 403 answers are permanent for the grant. Answers 404 when DEN_HEADLESS_RUNNER_CALLBACK_TOKEN is not configured.

## Response `200`

A fresh MCP token for the turn.

- object
  - `mcpToken` string, required
  - `expiresAt` string, date-time, required
  - `readOnly` boolean, required
  - `modelAccess` object
    - `baseUrl` string, uri, required
    - `apiKey` string, required
    - `protocol` 'anthropic' | 'openai' | 'openai-responses', required

## Other responses

- `400`: The body is not `{ grant, sessionId, messageId }`.
- `401`: Missing or wrong callback token.
- `403`: The grant is unknown, expired, revoked, for another turn, its member left, or the feature is off.
- `404`: Resume grants are not configured on this deployment.
- `429`: Too many exchanges for this grant; retry after `retryAfterMs`.
- `500`: The exchange failed; retry with backoff.

## Changes

- **2026-10-19** `f1d119370a1a`: 5 warning, 1 info
  - added the new `model_unavailable` enum value to the `error` response property for the response status `400`
  - added the new `model_unavailable` enum value to the `error` response property for the response status `401`
  - added the new `model_unavailable` enum value to the `error` response property for the response status `403`
  - added the new `model_unavailable` enum value to the `error` response property for the response status `404`
  - …2 more
- **2026-10-19** `21280947fa04`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/openworklabs/apis/den-api/changes/v1/headless/resume-token/post.md)

---

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