---
title: "Redeem an invitation token"
method: POST
path: "/redeem"
tags: ["Redemption"]
---

# Redeem an invitation token

`POST /redeem`

Public endpoint that the recipient's invite page posts the
token to. The server validates the token, loads the bound batch row, and
returns the next step as a flat result discriminated by `type`:

  - `RENDER_QR`: issuance is ready. Render a QR for `credentialOfferUrl` (an
    `openid-credential-offer://` URI) for the wallet to scan. `correlationId`
    and `credentialType` are included so the page can poll issuance progress
    and name the credential without re-parsing the URI.
  - `IDV_REDIRECT`: identity verification is required first. Navigate the
    user-agent to `dispatchUrl`.
  - `ERROR`: the flow halted with a message safe to show the recipient in
    `publicMessage`.

## Request body

- RedeemFlowArgs — Body of `POST /redeem`.
  - `token` string, required — The raw invitation token, taken from the `?t=` query parameter of the invite link.
  - `redemptionBaseUrl` string, uri, required — Absolute base URL the identity-verification callback should target. The flow appends `/redeem/idv-callback?t=<token>`. Typically the same origin the invite page was loaded from.

## Response `200`

Redemption proceeded; the result `type` indicates the next step.

- RedeemFlowResult — Flat result of `POST /redeem`, discriminated by `type`. Each type populates a different subset of the optional fields: - RENDER_QR: `credentialOfferUrl`, `correlationId`, `credentialType`. - IDV_REDIRECT: `dispatchUrl`. - ERROR: `publicMessage`.
  - `type` 'IDV_REDIRECT' | 'RENDER_QR' | 'ERROR', required — The next step for the recipient's user-agent.
  - `credentialOfferUrl` string, nullable — RENDER_QR only. The OID4VCI credential offer URI to render as a QR code.
  - `correlationId` string, nullable — RENDER_QR only. The OID4VCI session correlation id, also carried as the trailing segment of the offer URI. Use it to poll issuance progress.
  - `credentialType` string, nullable — RENDER_QR only. The credential type or configuration id being offered, for naming it in the UI.
  - `dispatchUrl` string, uri, nullable — IDV_REDIRECT only. The identity-verification engine URL to navigate the user-agent to.
  - `publicMessage` string, nullable — ERROR only. A sanitized message safe to display to the recipient.

## Other responses

- `400` — The request body was malformed, or the token's target is not a redeemable batch row.
- `403` — The invitation is expired or revoked, or identity verification did not match the expected recipient.
- `404` — The token is unknown, or its bound batch row no longer exists.
- `500` — unresolved $ref

---

[API](https://skmtc.dev/sphereon-opensource/apis/invitation-api.md) · [All operations](https://skmtc.dev/sphereon-opensource/apis/invitation-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/sphereon-opensource/invitation-api/revisions/f85ce680c5ac/schema)