---
title: "Allow one of your personal tokens to write the workspace guidance card, for a while"
method: POST
path: "/api/tokens/{tokenId}/guidance-grant"
tags: ["Tokens"]
---

# Allow one of your personal tokens to write the workspace guidance card, for a while

`POST /api/tokens/{tokenId}/guidance-grant`

## Request

- Base URL: `https://tre-app.com`
- URL: `https://tre-app.com/api/tokens/{tokenId}/guidance-grant`
- Auth: one of:
  - API key in cookie `__Secure-authjs.session-token`
  - API key in cookie `authjs.session-token`

Requires the authenticated web session; every Bearer token, including admin scope, receives 403 FORBIDDEN (Guidance write grants require the web session). The caller must be an owner or admin of `workspace` (403 otherwise; a slug that is not the caller's answers 404 NOT_FOUND) and `tokenId` must be one of their own live personal tokens (404 NOT_FOUND otherwise); a workspace-bound token can only be allowed for its own workspace (400). The grant lasts `durationMinutes` (default 60, at most 1440) and supersedes any open grant on the same token and workspace. It never replaces the owner/admin role the token's person must still hold at write time, and the granted write itself must carry `confirm: 'guidance'` and `expectedUpdatedAt` (see updateCard). Every granted write is recorded on the events ledger with the grant and the person who allowed it.

## Request body

- GuidanceGrantCreate
  - `workspace` string, required: The workspace whose guidance card the token may write. The caller must be an owner or admin of it; a workspace-bound token can only be allowed for its own workspace.
  - `durationMinutes` integer: How long the grant lasts, in minutes: 5 to 1440 (a day), default 60.

## Response `201`

Success

- GuidanceWriteGrant
  - `id` string, uuid, required
  - `tokenId` string, uuid, required
  - `workspace` string, required
  - `grantedBy` object, required
    - `id` string, uuid, nullable, required
    - `name` string, nullable, required
  - `grantedAt` string, date-time, required
  - `expiresAt` string, date-time, required
  - `revokedAt` string, date-time, nullable, required
  - `status` 'active' | 'expired' | 'revoked', required

## Other responses

- `400`: Invalid request
- `401`: Unauthenticated
- `403`: Guidance write grants require the web session, or the caller is not an owner or admin of the workspace
- `404`: Not found
- `409`: Conflict
- `429`: Rate limited
- `500`: Internal server error
- `503`: Temporarily unavailable

---

[API](https://skmtc.dev/tre-app/apis/tre-rest-api.md) · [All operations](https://skmtc.dev/tre-app/apis/tre-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/tre-app/apis/tre-rest-api/revisions/26a7187a05fc?raw)