Roles & Permissions

UrbanPayX 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. Also the default role for API key tokens.
DEVELOPER	Can manage webhooks, client settings, and view transactions. Cannot create payments or manage KYC.	Team members assigned this role. Intended for developers handling integration setup.

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
Rotate API key	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	Default: `developer`. If a valid dashboard bearer token is also provided, role is inherited from that account.	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-code

This 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. This is also what your server-to-server integration gets automatically via API key.

DEVELOPER — For engineers setting up the integration: configuring webhooks, updating client settings (callback URL, webhook URL), and monitoring transactions. Developers cannot create payments — 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