Permissions and scopes

How permissions work

Every operation requires a set of permissions, named in kebab case after what they allow (view-consumer-catalog, create-consumer-redemptions, manage-webhooks). A request is allowed when its principal holds all of the operation’s permissions.

Dashboard users hold the permissions of all their groups plus the permissions given to them directly, within one partner (Members and groups).
API keys hold exactly their scopes, chosen when the key is created. A key never inherits the permissions of the user who created it.
Some permissions are not delegable: they cover identity and security administration, payment authorisation and accepting prices, and can never be API-key scopes. Operations that need one can only be called by signed-in dashboard users.

A request without a required permission is refused with 403 missing-permission; more.requiredPermissions lists what the operation needs:

{
  "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": ["void-consumer-redemptions"] }
    }
  ]
}

Each page of the API reference ends with a line such as Required permissions: create-consumer-redemptions · API keys: allowed. A few workspace reads (for example workspace branding) show “none (any member or API key)”. Operations marked API keys: not allowed display the note “Dashboard session only”. GET /partner/v1/principal returns the effectivePermissions of the calling key or user, and GET /partner/v1/permissions lists every permission that applies to your partner.

Choosing scopes

Give each key the smallest set of scopes its system needs, and use separate keys for separate systems.

Integration	Scopes
Redeem vouchers in your app or backend	`view-consumer-catalog`, `create-consumer-redemptions`, `view-consumer-redemptions`
Manage customers as redemption entities (including GDPR erasure)	add `view-consumer-redemption-entities`, `manage-consumer-redemption-entities`, `erase-consumer-redemption-entities`
Void redemptions (for example on refunds)	add `void-consumer-redemptions`
Create Redemption Links	`view-consumer-catalog`, `view-consumer-redemption-links`, `manage-consumer-redemption-links`
Sync the catalog and set toggles	`view-consumer-catalog`, `manage-consumer-catalog`
Receive webhooks (manage endpoints, read delivery logs)	`view-webhooks`, `manage-webhooks`, `view-webhook-deliveries`
Fetch invoices into your ERP	`view-consumer-billing`
Check price acceptance before offering a set	`view-consumer-pricing`
Reporting	`view-consumer-analytics`, `view-consumer-redemptions`

Subscribing a webhook endpoint to billing events also needs view-consumer-billing, and to pricing events view-consumer-pricing, on the key or user that creates or edits the endpoint.

Permission reference

Workspace permissions (every partner)

Permission	Allows	Delegable to API keys
`view-profile`	Read your partner record and settings	yes
`manage-settings`	Edit contacts, locale, time zone, MFA policy, IP allowlist enforcement	no
`view-members`	List members and invitations	yes
`manage-members`	Invite, suspend and remove members; edit their direct permissions	no
`view-groups`	List groups	yes
`manage-groups`	Create, edit and delete groups and their members	no
`view-audit`	Read the audit log	yes
`request-api-access`	Request API access	no
`view-api-keys`	List API keys (metadata only)	no
`manage-api-keys`	Create, roll and revoke API keys	no
`view-webhooks`	List webhook endpoints	yes
`manage-webhooks`	Create, edit, pause and delete endpoints, rotate secrets, send test events and replay deliveries	yes
`view-webhook-deliveries`	Read the webhook delivery log	yes
`view-ip-allowlist`	Read the IP allowlist	yes
`manage-ip-allowlist`	Change the IP allowlist	no
`view-domains`	Read custom domains	yes
`manage-domains`	Add, re-check and delete custom domains	yes
`manage-workspace-branding`	Edit Workspace Branding and brand assets	yes
`view-sso`	Read single sign-on connections	no
`manage-sso`	Manage single sign-on connections and domain verification	no

Consumer permissions

Permission	Allows	Delegable to API keys
`view-consumer-catalog`	Read your catalog	yes
`manage-consumer-catalog`	Provider and Voucher Set Toggles, positions, featured flags, category overrides, settings, entity limits and your references	yes
`view-consumer-redemptions`	Read redemptions, including issued codes and links	yes
`create-consumer-redemptions`	Redeem vouchers (single and batch)	yes
`void-consumer-redemptions`	Void redemptions	yes
`view-consumer-redemption-entities`	Read redemption entities (including the email of entities created by the Email OTP Gate)	yes
`manage-consumer-redemption-entities`	Create, update, block and unblock redemption entities	yes
`erase-consumer-redemption-entities`	Erase redemption entities (GDPR)	yes
`view-consumer-redemption-links`	Read Redemption Links	yes
`manage-consumer-redemption-links`	Create, update and revoke Redemption Links	yes
`manage-consumer-email`	SMTP configuration, email templates and the email OTP setting	yes
`view-consumer-analytics`	Read statistics	yes
`view-consumer-billing`	Read the billing account, contacts, payment methods (masked), invoices (Stornorechnungen included), payments, usage and balance; download documents	yes
`manage-consumer-billing`	Edit the billing account and contacts, set up or remove SEPA mandates, resend documents	no
`view-consumer-pricing`	Read your Price Terms, upcoming price changes and Price Acceptances	yes
`accept-consumer-pricing`	Accept Price Terms (signed-in users only, with a recent sign-in)	no

Default groups Every consumer partner starts with these groups. You can create your own groups as well (Members and groups).

Group	Permissions
`owners`	All permissions. Cannot be changed
`administrators`	All permissions except `manage-sso` and `request-api-access`
`developers`	`view-profile`, `view-audit`, `request-api-access`, `view-api-keys`, `manage-api-keys`, `view-webhooks`, `manage-webhooks`, `view-webhook-deliveries`, `view-ip-allowlist`, `manage-ip-allowlist`, `view-domains`, and every other `view-*` permission except `view-consumer-billing` and `view-consumer-pricing`
`redemption-operators`	`view-profile`, `view-consumer-catalog`, `view-consumer-redemptions`, `create-consumer-redemptions`, `void-consumer-redemptions`, `view-consumer-redemption-entities`, `manage-consumer-redemption-entities`, `view-consumer-redemption-links`, `manage-consumer-redemption-links`
`billing`	`view-profile`, `view-consumer-billing`, `manage-consumer-billing`, `view-consumer-analytics`, `view-consumer-pricing`, `accept-consumer-pricing`
`viewers`	Every `view-*` permission except `view-api-keys`, `view-consumer-billing` and `view-consumer-pricing`

Get started

Authentication and security

API conventions

Webhooks

Consumer guides

Workspace

How permissions work

Choosing scopes

Permission reference

​How permissions work

​Choosing scopes

​Permission reference

​Related

How permissions work

Choosing scopes

Permission reference

Related