> ## Documentation Index > Fetch the complete documentation index at: https://docs-consumer.voucher.allride.io/llms.txt > Use this file to discover all available pages before exploring further. # Redeem a voucher > Allocates one voucher (first expiring first, never the same single-use voucher twice) from a voucher set (`voucherSetId`) or from the provider's best redeemable set (`providerId`) and returns the issued code or link. Optionally attaches a redemption entity by id or inline by `refId`, and stores your `metadata`. The response is sent only after the redemption is committed. Always send an `Idempotency-Key`: a replay returns the identical 201 including `issued`; a stored 409 is final for its key. Errors are checked in this order: unknown set (404), not redeemable (409 `voucher-set-unavailable`), no Price Acceptance (409 `price-acceptance-required`), entity problems, entity limit, stock. Sends the `redemption-created` webhook. See [Redeeming vouchers](/consumer/redeeming). **Required permissions:** `create-consumer-redemptions` · **API keys:** allowed ## OpenAPI ````yaml /openapi/consumer.v1.json post /consumer/v1/redemptions openapi: 3.1.1 info: title: AllRide Voucher Consumer API version: 1.0.0 description: >- The Consumer API (`/consumer/v1`) and the shared Workspace API (`/partner/v1`) of the AllRide Voucher Platform for Partner Consumers: browse your catalog, redeem vouchers, manage redemption entities and Redemption Links, configure email OTP, read analytics and billing, and administer your workspace. Start with the [quickstart](https://docs-consumer.voucher.allride.io/quickstart). This document lists the sandbox server; production uses `https://api.voucher.allride.io`. contact: name: AllRide url: https://allride.io servers: - url: https://api.voucher-staging.allride.io description: Sandbox security: - apiKey: [] tags: - name: Catalog description: >- Browse the providers, voucher sets and categories AllRide makes available to you. - name: Catalog settings description: >- Turn providers and voucher sets on or off for your channels and keep your own settings and references. - name: Redemptions description: >- Redeem vouchers (single or batch), read issued codes and links, and void redemptions. - name: Redemption entities description: Your end customers or accounts, identified by your own opaque `refId`. - name: Redemption links description: >- Shareable links that let an end customer redeem on an AllRide-hosted landing page. - name: Email (SMTP and templates) description: >- Email OTP Gate settings, your SMTP configuration and the OTP email templates. - name: Analytics description: Redemption, entity and link statistics in your partner time zone. - name: Billing description: >- Billing account, contacts, payment methods, invoices (including Stornorechnungen), payments, usage and balance. - name: Pricing description: Your resolved Price Terms per voucher set and your Price Acceptances. - name: Partner description: >- Your partner record, settings, principal introspection, API access and the developer reference. - name: Members description: Users of your partner and their invitations. - name: Groups description: Groups, their permissions and the permission catalog. - name: API keys description: API keys of your partner (dashboard only). - name: Webhook endpoints description: Webhook endpoints, their secrets and the event types you can subscribe to. - name: Webhook deliveries description: The webhook delivery log and replays. - name: IP allowlist description: Source address ranges allowed to call the API. - name: Custom domains description: Your own host names for Redemption Link landing pages. - name: Workspace branding description: Workspace Branding (dashboards and landing pages) and brand assets. - name: Single sign-on description: SAML and OIDC connections for your users. - name: Audit log description: Every change made in your partner, by whom and when. paths: /consumer/v1/redemptions: post: tags: - Redemptions summary: Redeem a voucher description: >- Allocates one voucher (first expiring first, never the same single-use voucher twice) from a voucher set (`voucherSetId`) or from the provider's best redeemable set (`providerId`) and returns the issued code or link. Optionally attaches a redemption entity by id or inline by `refId`, and stores your `metadata`. The response is sent only after the redemption is committed. Always send an `Idempotency-Key`: a replay returns the identical 201 including `issued`; a stored 409 is final for its key. Errors are checked in this order: unknown set (404), not redeemable (409 `voucher-set-unavailable`), no Price Acceptance (409 `price-acceptance-required`), entity problems, entity limit, stock. Sends the `redemption-created` webhook. See [Redeeming vouchers](/consumer/redeeming). **Required permissions:** `create-consumer-redemptions` · **API keys:** allowed operationId: consumer.redemptions.create parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRedemptionBody' examples: by-set: summary: Redeem from a voucher set with an inline entity value: voucherSetId: 2030 redemptionEntity: refId: customer:48213 metadata: redemptionReason: standard forMonth: 2026-10 by-provider: summary: Redeem from a provider value: providerId: 1030 redemptionEntityId: 9017 responses: '201': description: Created headers: X-Request-Id: $ref: '#/components/headers/XRequestId' Location: $ref: '#/components/headers/Location' Idempotent-Replayed: $ref: '#/components/headers/IdempotentReplayed' content: application/json: schema: $ref: '#/components/schemas/RedemptionResponse' examples: default: summary: Created value: data: id: 6017 resource: redemption status: completed channel: api providerPartnerId: 1030 voucherSetId: 2030 voucherSetRevisionNo: 2 voucherId: 5017 voucherSet: id: 2030 name: de: 5 € Fahrguthaben en: €5 ride credit providerDisplayName: de: Acme Scooters en: Acme Scooters issued: kind: code code: ACME5-7KQ2-M9XA link: https://acme-scooters.example.com/r?c=ACME5-7KQ2-M9XA validFrom: null validUntil: '2026-12-31T22:59:59Z' redemptionEntity: id: 9017 resource: redemption-entity refId: customer:48213 _links: self: href: >- https://api.voucher.allride.io/consumer/v1/redemption-entities/9017 type: application/json redemptionLink: null batchId: null metadata: redemptionReason: standard forMonth: 2026-10 actor: type: api-key id: 12017 label: Production integration idempotencyKey: order-8812:line-1 legacyRef: null redeemedAt: '2026-10-21T17:42:10.120Z' voidedAt: null voidedBy: null voidReason: null _links: self: href: >- https://api.voucher.allride.io/consumer/v1/redemptions/6017 type: application/json voucherSet: href: >- https://api.voucher.allride.io/consumer/v1/catalog/voucher-sets/2030 type: application/json redemptionEntity: href: >- https://api.voucher.allride.io/consumer/v1/redemption-entities/9017 type: application/json '400': description: Bad Request x-error-codes: - malformed-json - invalid-header - invalid-idempotency-key - data-failed-validation headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: malformed-json: summary: Malformed JSON value: errors: - message: >- The body is not valid UTF-8 JSON or nests deeper than 32 levels. statusCode: 400 errorCode: malformed-json invalid-header: summary: Invalid header value: errors: - message: >- A standard or platform header is malformed or missing; `more.validationErrors[].property` names it. statusCode: 400 errorCode: invalid-header invalid-idempotency-key: summary: Invalid Idempotency-Key value: errors: - message: >- The `Idempotency-Key` header is not 1-255 printable ASCII characters. statusCode: 400 errorCode: invalid-idempotency-key data-failed-validation: summary: Data failed validation value: errors: - message: >- One or more properties or parameters are invalid; each is listed in `more.validationErrors` with its property path and violated constraint. Unknown properties and query parameters are refused as well. statusCode: 400 errorCode: data-failed-validation more: validationErrors: - property: name constraint: required message: en: This property is required. '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': description: Not found. x-error-codes: - route-not-found - voucher-set-not-found - provider-not-found - redemption-entity-not-found headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: route-not-found: summary: Route not found value: errors: - message: No operation exists for this path. statusCode: 404 errorCode: route-not-found voucher-set-not-found: summary: Voucher set not found value: errors: - message: >- The voucher set does not exist, was never approved, or is not visible to you. statusCode: 404 errorCode: voucher-set-not-found provider-not-found: summary: Provider not found value: errors: - message: >- The provider does not exist or has no voucher set visible to you. statusCode: 404 errorCode: provider-not-found redemption-entity-not-found: summary: Redemption entity not found value: errors: - message: >- The redemption entity does not exist or belongs to another partner. statusCode: 404 errorCode: redemption-entity-not-found '409': description: Conflict x-error-codes: - idempotency-key-in-use - voucher-set-unavailable - price-acceptance-required - voucher-set-depleted - provider-depleted - entity-limit-reached - redemption-entity-blocked - redemption-entity-erased - voucher-already-redeemed headers: X-Request-Id: $ref: '#/components/headers/XRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: idempotency-key-in-use: summary: Idempotency-Key in use value: errors: - message: >- A request with the same `Idempotency-Key` is still being processed. statusCode: 409 errorCode: idempotency-key-in-use voucher-set-unavailable: summary: Voucher set unavailable value: errors: - message: >- The voucher set cannot be redeemed now: it is not active, its provider is not active, AllRide no longer grants you access, or your provider or voucher set toggle is off. statusCode: 409 errorCode: voucher-set-unavailable price-acceptance-required: summary: Price acceptance required value: errors: - message: >- You have not accepted the Price Terms in force at the redemption instant, or the voucher set has no price yet. statusCode: 409 errorCode: price-acceptance-required more: voucherSetId: 2030 priceAcceptanceStatus: acceptance-required voucher-set-depleted: summary: Voucher set depleted value: errors: - message: >- No voucher of the set can be issued: every voucher is redeemed, expired or revoked (in a batch: fewer distinct vouchers than requested). statusCode: 409 errorCode: voucher-set-depleted provider-depleted: summary: Provider depleted value: errors: - message: >- Every redeemable voucher set of the provider is depleted. statusCode: 409 errorCode: provider-depleted entity-limit-reached: summary: Entity limit reached value: errors: - message: >- The redemption entity has reached the per-entity limit you configured for the voucher set (`entityLimit`). statusCode: 409 errorCode: entity-limit-reached redemption-entity-blocked: summary: Redemption entity blocked value: errors: - message: The redemption entity is blocked. statusCode: 409 errorCode: redemption-entity-blocked redemption-entity-erased: summary: Redemption entity erased value: errors: - message: >- The redemption entity has been erased; erasure is irreversible. statusCode: 409 errorCode: redemption-entity-erased voucher-already-redeemed: summary: Voucher already redeemed value: errors: - message: >- A safety check found the voucher already redeemed. This is not expected in normal operation. statusCode: 409 errorCode: voucher-already-redeemed '422': description: Unprocessable Content x-error-codes: - idempotency-key-reused headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: idempotency-key-reused: summary: Idempotency-Key reused value: errors: - message: >- The `Idempotency-Key` was already used for a different request. statusCode: 422 errorCode: idempotency-key-reused '500': description: Unexpected failure; quote the `requestId`. x-error-codes: - internal-error - link-render-failed headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal-error: summary: Internal error value: errors: - message: Something went wrong on our side statusCode: 500 errorCode: internal-error requestId: 0c9f2ea5-fe09-463c-8f96-b6cae67800ad link-render-failed: summary: Link render failed value: errors: - message: Something went wrong on our side statusCode: 500 errorCode: link-render-failed requestId: 0c9f2ea5-fe09-463c-8f96-b6cae67800ad '503': description: Temporarily unavailable; retry after `Retry-After`. x-error-codes: - service-unavailable - db-unavailable - query-timeout - db-unavailable headers: X-Request-Id: $ref: '#/components/headers/XRequestId' Retry-After: $ref: '#/components/headers/RetryAfter' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: service-unavailable: summary: Service unavailable value: errors: - message: Something went wrong on our side statusCode: 503 errorCode: service-unavailable requestId: 0c9f2ea5-fe09-463c-8f96-b6cae67800ad db-unavailable: summary: Database unavailable value: errors: - message: Something went wrong on our side statusCode: 503 errorCode: db-unavailable requestId: 0c9f2ea5-fe09-463c-8f96-b6cae67800ad query-timeout: summary: Query timeout value: errors: - message: Something went wrong on our side statusCode: 503 errorCode: query-timeout requestId: 0c9f2ea5-fe09-463c-8f96-b6cae67800ad components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: >- Optional key (1-255 printable ASCII characters, no spaces; a UUID is ideal) that makes this POST safe to retry: the same key with the same request replays the stored response for 24 hours. See [Idempotency](/guides/idempotency). schema: type: string minLength: 1 maxLength: 255 pattern: ^[\x21-\x7E]{1,255}$ example: order-8812:line-1 schemas: CreateRedemptionBody: type: object description: >- Exactly one of `voucherSetId` and `providerId`; at most one of `redemptionEntityId` and `redemptionEntity`. properties: voucherSetId: $ref: '#/components/schemas/ULong' description: Redeem from this voucher set. providerId: $ref: '#/components/schemas/ULong' description: >- Redeem from the provider's best redeemable set (by your position, then activation). redemptionEntityId: $ref: '#/components/schemas/ULong' description: An existing redemption entity. redemptionEntity: $ref: '#/components/schemas/InlineRedemptionEntity' description: Inline entity, upserted by `refId`. metadata: anyOf: - $ref: '#/components/schemas/JsonMetadata' - type: 'null' description: >- Stored on the redemption and forwarded in the `redemption-created` webhook. Never put personal data here. required: [] additionalProperties: false RedemptionResponse: type: object description: Single-object envelope around a `Redemption`. properties: data: $ref: '#/components/schemas/Redemption' required: - data additionalProperties: false ErrorResponse: type: object description: >- Error body of every 4xx and 5xx response (`Content-Type: application/json`). properties: errors: type: array minItems: 1 items: $ref: '#/components/schemas/ErrorEntry' description: The errors; in v1 always exactly one. required: - errors additionalProperties: false ULong: type: integer format: uint64 minimum: 0 maximum: 18446744073709552000 x-bigint: true description: >- Unsigned 64-bit integer (ids and large counters). May exceed 2^53; parse with a BigInt-safe JSON parser in JavaScript. InlineRedemptionEntity: type: object properties: refId: type: string pattern: ^[A-Za-z0-9._:@/+=-]{1,128}$ minLength: 1 maxLength: 128 description: Your opaque reference; the entity is created or updated by `refId`. displayName: type: - string - 'null' maxLength: 120 description: At most 120 characters. metadata: anyOf: - $ref: '#/components/schemas/JsonMetadata' - type: 'null' description: When sent and different, updates the entity's metadata. required: - refId additionalProperties: false description: Redemption entity upserted by `refId` in the same transaction. JsonMetadata: type: object additionalProperties: true description: >- Free-form JSON object (at most 16 KiB, depth 5, 100 keys per object). The platform stores it as sent and never interprets it. Key order is not preserved. example: orderId: '8812' channel: app Redemption: type: object description: >- A redemption (consumer view). Append-only. Also the `payload` of the `redemption-created` and `redemption-voided` webhooks. properties: id: $ref: '#/components/schemas/ULong' description: Numeric id of the resource, unique per resource type. resource: type: string enum: - redemption description: Always `redemption`. status: type: string enum: - completed - voided description: 'Status. Treat as an open set: new values may be added.' channel: type: string enum: - api - dashboard - redemption-link - import description: >- `api` for API keys, `dashboard` for users, `redemption-link` for landing-page redemptions, `import` for imported history. Treat as an open set: new values may be added. providerPartnerId: $ref: '#/components/schemas/ULong' description: Provider of the voucher. voucherSetId: $ref: '#/components/schemas/ULong' description: Voucher set. voucherSetRevisionNo: type: integer description: Revision of the set in force at redemption. voucherId: $ref: '#/components/schemas/ULong' description: The allocated voucher. voucherSet: $ref: '#/components/schemas/RedemptionVoucherSetSummary' description: Historical names of the set and provider. issued: $ref: '#/components/schemas/IssuedVoucher' description: The issued code or link. validFrom: anyOf: - $ref: '#/components/schemas/Instant' - type: 'null' description: Voucher valid from. validUntil: anyOf: - $ref: '#/components/schemas/Instant' - type: 'null' description: Voucher valid until. redemptionEntity: anyOf: - $ref: '#/components/schemas/RedemptionEntitySummary' - type: 'null' description: The redemption entity. redemptionLink: anyOf: - $ref: '#/components/schemas/RedemptionLinkReference' - type: 'null' description: The Redemption Link used. batchId: anyOf: - $ref: '#/components/schemas/ULong' - type: 'null' description: Redemption batch. metadata: anyOf: - $ref: '#/components/schemas/JsonMetadata' - type: 'null' description: Metadata you sent with the redemption. Never put personal data here. actor: $ref: '#/components/schemas/Actor' description: Who redeemed. idempotencyKey: type: - string - 'null' description: >- The `Idempotency-Key` of the request (a batch stores it on every redemption). legacyRef: type: - string - 'null' description: Reference of imported history. redeemedAt: $ref: '#/components/schemas/Instant' description: When the voucher was redeemed. voidedAt: anyOf: - $ref: '#/components/schemas/Instant' - type: 'null' description: When the redemption was voided. voidedBy: anyOf: - $ref: '#/components/schemas/Actor' - type: 'null' description: Who voided it. voidReason: type: - string - 'null' description: Why it was voided. _links: type: object description: >- Related resources you may follow (HAL style). A link is present only when you hold the target's permissions. properties: self: $ref: '#/components/schemas/Link' description: This resource. voucherSet: $ref: '#/components/schemas/Link' description: The catalog entry, while visible. redemptionEntity: $ref: '#/components/schemas/Link' description: The redemption entity. redemptionLink: $ref: '#/components/schemas/Link' description: The Redemption Link. batch: $ref: '#/components/schemas/Link' description: The redemption batch. required: - self additionalProperties: false required: - id - resource - status - channel - providerPartnerId - voucherSetId - voucherSetRevisionNo - voucherId - voucherSet - issued - validFrom - validUntil - redemptionEntity - redemptionLink - batchId - metadata - actor - idempotencyKey - legacyRef - redeemedAt - voidedAt - voidedBy - voidReason - _links additionalProperties: false ErrorEntry: type: object description: One error. Branch on `errorCode`; ignore members you do not know. properties: message: type: string description: >- Human-readable message. For 5xx errors it is always the generic `Something went wrong on our side`. statusCode: type: integer description: The HTTP status. errorCode: type: string description: Stable kebab-case error code, listed in the error catalog. requestId: type: string description: >- 5xx only: the request id (also in the `X-Request-Id` header). Quote it when you contact support. more: type: object additionalProperties: true description: >- Additional details for some codes, for example `validationErrors` (array of `ValidationError`) or `requiredPermissions`. The members per code are listed in the error catalog. properties: validationErrors: type: array items: $ref: '#/components/schemas/ValidationError' description: Invalid properties or parameters. required: - message - statusCode - errorCode additionalProperties: true RedemptionVoucherSetSummary: type: object description: Historical names of the redeemed voucher set and its provider. properties: id: $ref: '#/components/schemas/ULong' description: Voucher set id. name: $ref: '#/components/schemas/I18nText' description: Name of the set in the revision in force at redemption. providerDisplayName: $ref: '#/components/schemas/I18nText' description: Provider name at redemption. required: - id - name - providerDisplayName additionalProperties: false IssuedVoucher: type: object description: >- The voucher handed out. Readable again with `GET /consumer/v1/redemptions/{redemptionId}`. properties: kind: type: string enum: - code - link description: 'What was issued. Treat as an open set: new values may be added.' code: type: - string - 'null' description: 'The voucher code. A secret: show it only to the entitled customer.' link: type: - string - 'null' format: uri pattern: ^https:// description: The voucher link (or the rendered dynamic link of a code). required: - kind - code - link additionalProperties: false Instant: type: string format: date-time description: >- RFC 3339 timestamp in UTC with `Z`, millisecond precision, truncated: no fraction when the milliseconds are zero (`2026-11-01T00:00:00Z`), otherwise exactly three digits (`2026-10-21T17:42:10.120Z`). Inputs must carry an offset and are normalised to UTC. example: '2026-11-01T00:00:00Z' RedemptionEntitySummary: type: object description: Summary of a redemption entity. properties: id: $ref: '#/components/schemas/ULong' description: Numeric id of the resource, unique per resource type. resource: type: string enum: - redemption-entity description: Always `redemption-entity`. refId: type: - string - 'null' pattern: ^[A-Za-z0-9._:@/+=-]{1,128}$ minLength: 1 maxLength: 128 description: Current `refId` of the entity (`null` once erased). _links: type: object description: >- Related resources you may follow (HAL style). A link is present only when you hold the target's permissions. properties: self: $ref: '#/components/schemas/Link' description: This resource. required: - self additionalProperties: false required: - id - resource - refId - _links additionalProperties: false RedemptionLinkReference: type: object description: >- The Redemption Link a redemption was made through, with the link metadata snapshot. properties: id: $ref: '#/components/schemas/ULong' description: Numeric id of the resource, unique per resource type. resource: type: string enum: - redemption-link description: Always `redemption-link`. metadata: anyOf: - $ref: '#/components/schemas/JsonMetadata' - type: 'null' description: Snapshot of the link's metadata at redemption time. _links: type: object description: >- Related resources you may follow (HAL style). A link is present only when you hold the target's permissions. properties: self: $ref: '#/components/schemas/Link' description: This resource. required: - self additionalProperties: false required: - id - resource - metadata - _links additionalProperties: false Actor: type: object description: >- Who performed an action. AllRide staff appear as `{"type": "admin-user", "id": null, "label": "AllRide"}`. properties: type: type: string enum: - partner-user - api-key - admin-user - system - end-customer description: 'Kind of actor. Treat as an open set: new values may be added.' id: anyOf: - $ref: '#/components/schemas/ULong' - type: 'null' description: Id of the user or API key; `null` for AllRide staff and the system. label: type: string description: >- Display label (email of the user, API key name, `AllRide`, `System`). required: - type - id - label additionalProperties: false example: type: api-key id: 12017 label: Production integration Link: type: object description: A link to a related resource. properties: href: type: string format: uri description: Absolute URL. type: type: string description: Media type of the target, usually `application/json`. required: - href - type additionalProperties: false ValidationError: type: object description: >- One invalid property or parameter of a `data-failed-validation` error (also used for item failures of batch operations and content checks). properties: property: type: string description: >- Path of the offending property in your request body (`items[2].quantity`), or the name of the query parameter, path parameter or header. constraint: type: string description: >- The violated rule as a kebab-case item code, for example `required`, `too-long`, `invalid-id`, `unknown-field`. See the validation item codes in the error catalog. params: type: object additionalProperties: true description: >- Parameters of the constraint, for example `min` and `max` for `invalid-page` or `allowed` for `invalid-sort`. value: description: The rejected value, when it is safe to return. message: type: object description: Explanation per locale. properties: en: type: string description: English message. de: type: string description: German message. required: - en additionalProperties: false required: - property - constraint - message additionalProperties: true I18nText: type: object description: >- Localised text: an object keyed by locale (`de`, `en`). Responses always return the full map; pick the locale on your side. Requests must include your partner's default locale. properties: de: type: string description: German text. en: type: string description: English text. additionalProperties: false example: de: 5 € Fahrguthaben en: €5 ride credit headers: XRequestId: description: Request id (yours if you sent a valid `X-Request-Id`, else generated). schema: type: string Location: description: Absolute URL of the created resource or the job to poll. schema: type: string format: uri IdempotentReplayed: description: >- `true` when this response is a replay of a stored response for the same `Idempotency-Key`. schema: type: string enum: - 'true' RetryAfter: description: Seconds to wait before retrying or polling. schema: type: integer responses: Unauthorized: description: 'Unauthorized: the credential is missing or invalid.' x-error-codes: - unauthenticated - token-invalid - token-expired - api-key-invalid headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthenticated: summary: Authentication required value: errors: - message: No credential was sent with the request. statusCode: 401 errorCode: unauthenticated token-invalid: summary: Invalid credential value: errors: - message: >- The credential cannot be verified for this surface (wrong scheme, signature or credential kind). statusCode: 401 errorCode: token-invalid token-expired: summary: Credential expired value: errors: - message: The dashboard ID token has expired. statusCode: 401 errorCode: token-expired api-key-invalid: summary: Invalid API key value: errors: - message: >- The API key is unknown, revoked, expired, past its roll grace period or belongs to the other environment (`vk_test_` against production or `vk_live_` against the sandbox). statusCode: 401 errorCode: api-key-invalid Forbidden: description: 'Forbidden: an access gate refused the request.' x-error-codes: - partner-role-missing - partner-suspended - partner-offboarded - api-access-inactive - ip-not-allowed - mfa-required - sso-required - missing-permission - reauthentication-required headers: X-Request-Id: $ref: '#/components/headers/XRequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: partner-role-missing: summary: Partner role missing value: errors: - message: >- Your partner lacks the role (provider or consumer) this surface needs. statusCode: 403 errorCode: partner-role-missing more: requiredRole: consumer partner-suspended: summary: Partner suspended value: errors: - message: >- Your partner is suspended: writes are refused (billing writes from the dashboard excepted). statusCode: 403 errorCode: partner-suspended partner-offboarded: summary: Partner offboarded value: errors: - message: Your partner has been offboarded; every route is refused. statusCode: 403 errorCode: partner-offboarded api-access-inactive: summary: API access inactive value: errors: - message: >- API access of your partner is not active (not yet granted, revoked, or the partner is suspended), so API keys are refused. statusCode: 403 errorCode: api-access-inactive ip-not-allowed: summary: IP address not allowed value: errors: - message: >- The request's source address is not in your IP allowlist while enforcement is on. statusCode: 403 errorCode: ip-not-allowed mfa-required: summary: Multi-factor authentication required value: errors: - message: >- Your partner requires multi-factor authentication for dashboard users. statusCode: 403 errorCode: mfa-required sso-required: summary: Single sign-on required value: errors: - message: >- Your partner enforces single sign-on for this user's email domain. statusCode: 403 errorCode: sso-required missing-permission: summary: Missing permission value: errors: - message: >- The membership or API key lacks a permission the operation requires, including non-delegable permissions called with an API key. statusCode: 403 errorCode: missing-permission more: requiredPermissions: - create-consumer-redemptions reauthentication-required: summary: Recent sign-in required value: errors: - message: >- The operation needs a sign-in within the last 15 minutes (dashboard users only). statusCode: 403 errorCode: reauthentication-required securitySchemes: apiKey: type: http scheme: bearer bearerFormat: vk_live__ description: >- Your API key in `Authorization: Bearer `. Use `vk_test_…` keys against the sandbox and `vk_live_…` keys against production. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.