Role-based access control: OWNER, OPERATIONS, and DEVELOPER roles, permissions matrix, and security challenges.
Roles & Permissions
UrbanPay uses role-based access control to determine what each team member — or API token — can do. Every authenticated request carries a role, and the API enforces permissions at the endpoint level.
The three roles
| Role | Description | Who has it |
|---|---|---|
| OWNER | Full access. Can manage team members, configure security settings, and perform all operations. | The account creator. Additional owners can be promoted by an existing owner. |
| OPERATIONS | Can manage OpCos, projects, payments, KYC, and billing. Cannot manage team members or webhook configuration. | Team members assigned this role. |
| DEVELOPER | Can manage webhooks and view transactions. Cannot create payments, manage KYC, or update general client settings (callback URL etc.) — those are OWNER/OPERATIONS only. | Team members assigned this role. Intended for developers handling integration setup. |
Your workspace owner can also define additional custom roles for dashboard team members with a hand-picked set of permissions, beyond these three built-in templates. Custom roles are managed from the dashboard and cannot be assigned to API credentials, which must use one of OWNER, OPERATIONS, or DEVELOPER.
Permissions matrix
| Action | OWNER | OPERATIONS | DEVELOPER |
|---|---|---|---|
| OpCos | |||
| Create / update / submit OpCo | Y | Y | — |
| List / view OpCos | Y | Y | Y |
| Projects | |||
| Create / update project | Y | Y | — |
| List / view projects | Y | Y | Y |
| Payments / Transactions | |||
| Generate payment link | Y | Y | — |
| Refresh transaction status | Y | Y | — |
| Export transactions | Y | Y | — |
| List / view transactions | Y | Y | Y |
| KYC / Users | |||
| Create users | Y | Y | — |
| Initiate KYC verification | Y | Y | — |
| Update external verification status | Y | Y | — |
| Bulk user operations | Y | Y | — |
| List / view user KYC status | Y | Y | Y |
| Webhooks | |||
| Manage webhook subscriptions | Y | — | Y |
| Rotate webhook secret | Y | — | Y |
| Send test webhook | Y | — | Y |
| View webhook events/subscription/deliveries | Y | Y | Y |
| Configuration | |||
Update client settings (/auth/client/settings) | Y | Y | — |
| Team management | |||
| Add / update / delete team members | Y | — | — |
| Change member roles | Y | — | — |
| Reset member passwords | Y | — | — |
| Security / MFA | |||
Reset an API credential's secret (POST /auth/api-credentials/{id}/reset-secret) | Y | Y | Y |
| Configure client MFA defaults | Y | Y | — |
| Manage own MFA (enroll/confirm/disable TOTP, update own MFA settings) | Y | Y | Y |
| Billing | |||
| View invoices | Y | Y | — |
| Support tickets | |||
| Create / view / reply / close tickets | Y | Y | Y |
| Account | |||
View client profile (/auth/client/me) | Y | Y | Y |
View own team account (/auth/team/accounts/me) | Y | Y | Y |
API key tokens vs dashboard tokens
API key token (POST /api/v1/auth/api-token) | Dashboard token (POST /api/v1/auth/login) | |
|---|---|---|
| Actor type | client_api (default) | client_user |
| Role | Set explicitly when the credential is created (owner, operations, or developer) — there is no default, and different credentials for the same client can carry different roles. A credential can also be scoped to a custom set of individual permissions instead of a role template. | Role of logged-in team member |
| Access token TTL | 7 days | 30 minutes |
| Refresh token | Not issued | Issued (30 days) |
| MFA | Not applicable | Full MFA support |
What happens when you lack permission
If your token role does not have permission for an endpoint, the API returns:
HTTP 403 Forbidden
{
"detail": "Insufficient permissions for this action"
}Some endpoints also require a dashboard token specifically (not an API key token):
HTTP 403 Forbidden
{
"detail": "This action requires a dashboard account token"
}Sensitive actions and security challenges
Certain high-impact operations require an additional security verification step, regardless of your role. These include:
- Rotating your API key and secret
- Adding team members
- Disabling TOTP
The flow works like this:
1. Request a security code:
POST /api/v1/auth/security/request-codeThis sends a one-time code to your email (or you can use your TOTP authenticator app).
2. Include the security headers in the sensitive request:
X-Security-Token: <challenge_token_from_step_1>
X-Security-Code: <the_code_you_received>
X-Security-Method: email (or "totp" if using authenticator)Security codes expire after 5 minutes.
Choosing the right role for your team
OWNER — For founders, CTOs, or anyone who needs full control. Every account needs at least one active OWNER (the API prevents deleting or demoting the last one).
OPERATIONS — For team members who handle day-to-day payment operations: creating OpCos, managing users, generating payment links, viewing billing.
DEVELOPER — For engineers setting up the integration: configuring webhooks (including the webhook URL) and monitoring transactions. Developers cannot create payments, manage KYC, or update the callback URL and other general client settings (OWNER/OPERATIONS only) — that is by design, to separate integration setup from payment operations.
Related guides
- Authentication Guide — Token lifecycle, MFA, refresh flows
- Error Reference — All permission-related errors and how to fix them
- Getting Started — Your first API call with authentication