Vouchers

Voucher API

Endpoints, scopes, and constraints for independent application tokens.

Authentication

Runtime endpoints use an sop_ token. Do not send an account JWT or Bot Token to these endpoints.

Authorization: Bearer sop_xxxxxxxxxxxxxxxxx
Content-Type: application/json

Scopes

vouchers:readRead templates and redemption results

vouchers:templates:writeCreate and submit templates

vouchers:issueIssue vouchers

vouchers:verifyVerify voucher state

vouchers:redeemRedeem vouchers

vouchers:reverseReverse redemptions

Template endpoints

GET  /api/v1/open-platform/vouchers/templates
POST /api/v1/open-platform/vouchers/templates
POST /api/v1/open-platform/vouchers/templates/:templateId/submit

New templates start as draft, become reviewing after submission, and become active after platform approval.

Issuance and redemption endpoints

POST /api/v1/open-platform/vouchers/issue
POST /api/v1/open-platform/vouchers/verify
POST /api/v1/open-platform/vouchers/redeem
GET  /api/v1/open-platform/vouchers/redemptions/:redemptionId
POST /api/v1/open-platform/vouchers/redemptions/:redemptionId/reverse

Voucher credential

{
  "credential": {
    "type": "qr_token",
    "value": "SCANNED_VALUE"
  }
}

type accepts qr_token or redeem_code. Verification does not change voucher state.

Console management endpoints

These endpoints use the signed-in account JWT and only access applications owned by that account.

GET    /api/v1/open-platform/applications
POST   /api/v1/open-platform/applications
GET    /api/v1/open-platform/applications/:id
PATCH  /api/v1/open-platform/applications/:id
GET    /api/v1/open-platform/applications/:id/tokens
POST   /api/v1/open-platform/applications/:id/tokens
DELETE /api/v1/open-platform/applications/:id/tokens/:tokenId
PUT    /api/v1/open-platform/applications/:id/bots/:botId
DELETE /api/v1/open-platform/applications/:id/bots/:botId

Common status codes

401 The token is invalid, expired, or revoked.
403 The application is disabled, the feature is unavailable, or the token lacks scope.
404 The template, voucher, or redemption does not belong to the application.
409 State conflict, quota exhausted, or an idempotency key reused with a different request.
429 The request exceeded the endpoint rate limit.