Permissions and scopes

How permissions work

Every operation requires a set of permissions; a request needs all of them.

A dashboard user has the permissions of their groups plus their direct permissions in the partner (their effective permissions).
An API key has exactly its scopes, never the permissions of the user who created it.

A missing permission is 403 missing-permission; the error entry lists what was missing in more.requiredPermissions:

{
  "errors": [
    {
      "message": "The membership or API key lacks a permission the operation requires.",
      "statusCode": 403,
      "errorCode": "missing-permission",
      "more": { "requiredPermissions": ["upload-provider-vouchers"] }
    }
  ]
}

Each API reference page ends with Required permissions and API keys: allowed | not allowed. Operations that API keys can never call (security administration such as API keys, members, groups and the IP allowlist) answer 403 missing-permission to a key. One read needs no permission at all: the workspace branding (GET /partner/v1/branding/workspace) is readable by any member and any API key. GET /partner/v1/permissions lists the catalog with delegable and applicable flags.

Choosing scopes

Give each key only what its system does:

Integration	Scopes
Read-only monitoring	`view-profile`, `view-provider-voucher-sets`, `view-provider-redemptions`, `view-provider-analytics`
Inventory sync	`view-profile`, `view-provider-voucher-sets`, `view-provider-vouchers`, `upload-provider-vouchers`, `revoke-provider-vouchers`
Catalog management	`view-provider-voucher-sets`, `manage-provider-voucher-sets`, `submit-provider-voucher-sets`, `activate-provider-voucher-sets`
Webhook management	`view-webhooks`, `manage-webhooks`, `view-webhook-deliveries`

Avoid reveal-provider-vouchers on keys unless a system really needs clear values: every reveal is audited.

Permission reference

Workspace permissions (every partner):

Permission	Grants	Delegable to API keys
`view-profile`	Read your partner record, API access, developer reference, time zones	yes
`manage-settings`	Contacts, locale, time zone, MFA policy, IP allowlist enforcement	no
`view-members`	List members and invitations	yes
`manage-members`	Invite, suspend, remove members; direct permissions	no
`view-groups`	List groups and the permission catalog	yes
`manage-groups`	Create, edit, 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, rename, roll and revoke API keys	no
`view-webhooks`	List webhook endpoints and event types	yes
`manage-webhooks`	Create, edit, pause, delete endpoints, rotate secrets, test events, replays	yes
`view-webhook-deliveries`	Read the webhook delivery log	yes
`view-ip-allowlist` / `manage-ip-allowlist`	Read / change the IP allowlist	yes / no
`manage-workspace-branding`	Workspace branding and its images	yes
`view-sso` / `manage-sso`	Single sign-on connections	no / no

Provider permissions (providers only):

Permission	Grants	Delegable to API keys
`view-provider-profile`	Read provider profile, listing branding, their changelogs and brand assets	yes
`manage-provider-profile`	Profile and listing branding change requests, brand assets	yes
`view-provider-voucher-sets`	Read voucher sets, revisions, changelogs, change requests, stock, categories	yes
`manage-provider-voucher-sets`	Create sets, edit drafts and `internalName`, archive	yes
`submit-provider-voucher-sets`	Create, edit, submit and withdraw voucher set change requests	yes
`activate-provider-voucher-sets`	Activate, deactivate, schedule, cancel schedules	yes
`view-provider-vouchers`	List vouchers (masked) and uploads	yes
`reveal-provider-vouchers`	Reveal one voucher value at a time (audited)	yes
`upload-provider-vouchers`	Uploads and batch create	yes
`revoke-provider-vouchers`	Revoke vouchers	yes
`manage-provider-stock-alerts`	Edit stock alert rules	yes
`view-provider-redemptions`	Read redemptions (provider projection)	yes
`view-provider-analytics`	Read statistics	yes

Consumer permissions exist for partners with the consumer role; they are documented on the consumer docs site.

Get started

Authentication and security

API conventions

Webhooks

Provider 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