> ## 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.

# Permissions and scopes

> How permissions decide what a user or API key may do, how to choose API key scopes, and the full permission reference.

## 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](https://docs-consumer.voucher.allride.io/workspace/members-and-groups.md)).
* **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`](https://docs-consumer.voucher.allride.io/errors/catalog#missing-permission); `more.requiredPermissions` lists what the operation needs:

```json theme={null}
{
  "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](https://docs-consumer.voucher.allride.io/api-reference/consumer-redemptions-create.md) ends with a line such as **Required permissions:** `create-consumer-redemptions` · **API keys:** allowed. A few workspace reads (for example [workspace branding](https://docs-consumer.voucher.allride.io/api-reference/partner-workspace-branding-get.md)) show "none (any member or API key)". Operations marked **API keys: not allowed** display the note "Dashboard session only".

[`GET /partner/v1/principal`](https://docs-consumer.voucher.allride.io/api-reference/partner-principal-get) returns the `effectivePermissions` of the calling key or user, and [`GET /partner/v1/permissions`](https://docs-consumer.voucher.allride.io/api-reference/partner-permissions-list) 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](https://docs-consumer.voucher.allride.io/workspace/members-and-groups.md)).

| 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` |

## Related

* [API keys](https://docs-consumer.voucher.allride.io/guides/api-keys.md)
* [Members and groups](https://docs-consumer.voucher.allride.io/workspace/members-and-groups.md)
* [Authentication](https://docs-consumer.voucher.allride.io/guides/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.