---
title: "Issue a Right Token (the verificationCode is returned exactly once)"
method: POST
path: "/api/rightos/tokens/issue"
tags: ["tokens"]
---

# Issue a Right Token (the verificationCode is returned exactly once)

`POST /api/rightos/tokens/issue`

## Request

- Base URL: `https://rightos.i-s3.com`
- URL: `https://rightos.i-s3.com/api/rightos/tokens/issue`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-rightos-key`

Issues a digital QR ticket at one of your locations. The response's verificationCode and walletUrl are shown exactly once — hand the walletUrl (QR) to the end user. Omit endTime to apply the location policy's defaultValidityMinutes; after endTime, verification returns expired. 402 when the plan's monthly token limit is exceeded.

## Request body

- object
  - `locationId` string, required
  - `title` string, required
  - `description` string
  - `startTime` string, date-time
  - `endTime` string, date-time

## Response `201`

Issued

- IssuedTokenResponse
  - `token` RightToken: Public Right Token. The secretHash is never exposed by any endpoint.
    - `id` string
    - `organizationId` string
    - `locationId` string
    - `title` string
    - `description` string
    - `startTime` string, date-time
    - `endTime` string, date-time
    - `priorityNumber` integer: Daily issue sequence at this location (includes cancelled/used/expired). Not the live queue position — see queuePosition
    - `queuePosition` integer: Position in the active queue at issuance (issued + verified, not expired). ADR-0024
    - `status` 'issued' | 'verified' | 'used' | 'cancelled' | 'expired'
    - `transferCount` integer: Number of times transferred. 0 = original holder.
    - `createdAt` string, date-time
    - `usedAt` string, date-time
    - `cancelledAt` string, date-time
    - `transferredAt` string, date-time
  - `verificationCode` string: Returned exactly once. The server stores only its SHA-256 hash and cannot re-issue it.
  - `walletUrl` string: Right Wallet URL (QR display) to hand to the end user.

## Other responses

- `401`: Missing or invalid API key (error: missing_api_key | invalid_api_key)
- `402`: Plan limit exceeded (HTTP 402). Upgrade the plan to continue.
- `403`: Location belongs to another organization, or location_inactive
- `409`: queue_full — maxActiveTokens policy limit reached

---

[API](https://skmtc.dev/i-s3/apis/rightos-right-api.md) · [All operations](https://skmtc.dev/i-s3/apis/rightos-right-api/llms.txt) · [OpenAPI document](https://skmtc.dev/i-s3/apis/rightos-right-api/revisions/10020536e345?raw)