Roles & Permissions

A role is a named set of permissions that controls which portal screens, actions, and API endpoints a team member or API key can access.

This page covers how to create roles, assign permissions, attach roles to users and API keys, and reason about the permission model.

When to Use

• Onboarding new team members who should not have full Tenant Admin access.
• Restricting a service-account API key to the smallest set of operations it needs.
• Separating read-only access (analysts, support agents) from write access (billing operators, platform engineers).
• Building an approval workflow where one role can create campaigns and another can publish them.

Built-in Roles

Every tenant ships with a baseline set of roles. Built-in roles cannot be deleted but can be cloned to create a custom variant.

Role	Typical use
Tenant Admin	Full administrative authority. Manages all settings, users, and integrations.
Operator	Day-to-day operations: subscriptions, customers, refunds, goodwill.
Support Agent	Read-only customer view plus limited subscription actions (pause, defer).
Read-only	View-only access to all data. No write permissions.
Service Account	Programmatic access. Attach to API keys only, not human users.

Create a Custom Role

1. Sign in to the portal as a Tenant Admin.
2. Open Settings → Team → Roles.
3. Click Create Role.
4. Name the role (for example billing-reader).
5. Pick a starting template, or start from an empty permission set.
6. Tick the permissions the role should grant (see the permission groups below).
7. Click Save.

Permission Groups

Permissions are grouped by domain. Each permission unlocks specific portal actions and API endpoints.

Group	Sample permissions
Customers	customer.read, customer.write, customer.delete
Subscriptions	subscription.read, subscription.cancel, subscription.defer, subscription.reactivate
Catalog	bundle.read, bundle.write, priceCard.write, trialPolicy.write
Campaigns	campaign.read, campaign.write, campaign.publish, promoCode.issue
Payments	payment.read, payment.refund, paymentAdapter.configure
Webhooks	webhook.read, webhook.write, webhook.rotateSecret
Notifications	notificationTemplate.read, notificationTemplate.write, placeholder.manage
Tenant	tenant.settings.write, apiKey.manage, role.manage

Attach a Role to a Team Member

1. Open Settings → Team → Members.
2. Pick the team member.
3. Open the Roles tab.
4. Select one or more roles.
5. Click Save.

Permissions are additive: a user with two roles gets the union of both permission sets.

Attach a Role to an API Key

API keys take exactly one role at creation time. To change the role, generate a new key with the desired role and revoke the old one - see API Keys.

Test a Role

Use the Impersonate action (Tenant Admin only) to view the portal as a user with that role. This reveals exactly which screens and buttons are visible.

For API keys, run a smoke test against a Sandbox key:

curl -i https://api.azotte.com/v1/bundles \
  -H "x-tn: <your-tenant-id>" \
  -H "Authorization: Bearer <sandbox-api-key>"

A 403 Forbidden response means the role is missing the required permission.

Security Rules

• Apply least privilege. Start from empty and add permissions, not the other way around.
• Separate read and write roles for sensitive domains (payments, campaigns).
• Audit role assignments quarterly. Remove roles from users who no longer need them.
• Never grant tenant.settings.write or role.manage to a service-account API key.
• Log all role changes through the audit log: role.created, role.updated, role.assigned.

Related

• API Keys - attach a role to an API key.
• Terminology - definitions of Role, Team Member, and Tenant Admin.