---
title: "Generate a review-link token"
method: POST
path: "/api/v1/reviews/{id}/token"
tags: ["Reviews"]
---

# Generate a review-link token

`POST /api/v1/reviews/{id}/token`

## Request

- Base URL: `https://api.gatewerk.com`
- URL: `https://api.gatewerk.com/api/v1/reviews/{id}/token`
- Auth: HTTP bearer

Mints a single-use token and URL path (`/r/{token}`) that lets an unauthenticated reviewer decide this review. Requires the template to have `enable_review_links: true` and the review to be `pending`.

## Request body

- object
  - `purpose` string, required: Short, operator-supplied reason this token is being minted. Surfaced in the audit trail.
  - `recipient_label` string, required: Human-readable label for the recipient (e.g., name or email). Surfaced in the audit trail and inbox.
  - `note` string, nullable: Optional free-form note attached to the token.
  - `auth_level` 'public' | 'email_otp' | 'account': Auth tier required to consume the token. All three tiers are fully supported. 'public' asks nothing of the recipient and leaves the decision unattributed beyond recipient_label. 'email_otp' requires auth_email and makes the recipient prove control of that address with a 6 digit code before deciding. 'account' requires auth_user_id and makes the recipient sign in. The wire default stays 'public' for back-compat; the Inbox share dialog defaults to 'email_otp'.
  - `auth_email` string, email, nullable: Email pinned to the token when auth_level is email_otp.
  - `auth_user_id` string, nullable: Reviewer id pinned to the token when auth_level is account.
  - `expiryHours` integer: Hours until the token expires. Defaults to 48.

## Response `201`

Token created

- ReviewToken
  - `object` 'review_token', required
  - `token` string, required: Raw token. Returned once — store it client-side.
  - `review_id` string, required
  - `expires_at` string, date-time, nullable
  - `url` string, required: Path component (e.g. `/r/{token}`). Prefix with your UI origin.

## Other responses

- `400`: 400 Bad Request. Validation failed.
- `401`: 401. Missing or invalid API key.
- `404`: 404. Resource not found.
- `409`: 409. The review, its template, or the deployment cannot support the requested link. Codes: 'monitoring_not_shareable' (a monitoring review is never shareable), 'no_recipient_action' (the template exposes no decision action to a link recipient), 'smtp_not_configured' (auth_level 'email_otp' needs outbound email configured, since a code that can never be sent strands the recipient).
- `422`: 422. Cross-field validation failed. Returned when the contextual field required by the chosen auth_level is absent, or when a field belonging to another tier is present. Codes: 'auth_level.email_required', 'auth_level.user_id_required', 'auth_level.contextual_fields_not_allowed_for_public', 'auth_level.user_id_not_allowed_for_email_otp', 'auth_level.email_not_allowed_for_account'.

---

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