About users and roles

User accounts

A user represents an individual who interacts with Reefpay. Users are always associated with a single client (merchant or reseller).

User properties

Field	Description
`id`	Unique identifier (for example, `USER-3MtwBwLkdIwHu7ix28a3tqPa`)
`first_name`	User's first name
`last_name`	User's last name
`email`	Email address (used for login)
`phone`	Phone number
`time_zone`	User's time zone (for example, `America/New_York`)
`is_active`	Whether the account is active
`is_locked`	Whether the account is locked (for example, after failed login attempts)
`is_mfa_active`	Whether multi-factor authentication is enabled

User–client relationship

Every user belongs to exactly one client. The client's type (merchant or reseller) determines the scope of data the user can access.

User belongs to	Can access data for
Merchant	That merchant only
Reseller	The reseller and all clients in its subtree (child merchants, sub-resellers, their merchants)

Role-based access control

Users are assigned a role_id that determines their permissions. Roles control access to API endpoints, web portal features, and data visibility.

Common role types

Role	Scope	Typical permissions
Admin	Full access	Create/update clients, manage users, manage integrations, view all transactions, close batches
Manager	Operational access	View transactions and reports, manage payment tokens, close batches, manage users within their client
Operator	Day-to-day access	Process transactions, view transactions, manage payment tokens
Read-only	Reporting access	View transactions and reports only — no write operations

Role assignment

Roles are assigned when creating a user and can be updated later. The role_id field in the ClientInfo schema links a user to their role within a specific client context.

Permission matrix

Action	Admin	Manager	Operator	Read-only
Create/update clients	Yes	No	No	No
Manage integrations	Yes	No	No	No
Create/update users	Yes	Yes (own client)	No	No
Process transactions	Yes	Yes	Yes	No
Capture / cancel / refund	Yes	Yes	Yes	No
View transactions	Yes	Yes	Yes	Yes
View reports	Yes	Yes	Yes	Yes
Close batches	Yes	Yes	No	No
Manage payment tokens	Yes	Yes	Yes	No
Manage API keys	Yes	No	No	No

Managing users

Create a user

Create a new user with POST /v1/users.

POST /v1/users

{
  "first_name": "Jane",
  "last_name": "Smith",
  "email": "jane.smith@example.com",
  "phone": "+15559876543",
  "time_zone": "America/Chicago",
  "is_mfa_active": true,
  "is_active": true
}

List users

Retrieve all users for the authenticated client with GET /v1/users.

curl -X GET \
  https://api.dev.paradisegateway.net/v1/users \
  -H "APIKEY: YOUR-API-KEY"

Retrieve a user

Get details for a specific user with GET /v1/users/{id}.

Update a user

Update user properties with POST /v1/users/{id}. You can update name, phone, time zone, active status, and MFA settings.

User API endpoints

Operation	Endpoint	Method
Create	`/v1/users`	POST
List	`/v1/users`	GET
Retrieve	`/v1/users/{id}`	GET
Update	`/v1/users/{id}`	POST

Authentication

Users authenticate to obtain an API key. The API key is then used for all subsequent API requests.

Retrieve an API key: POST /v1/auth/keys with user_name (email) and password.
Use the API key: Include the APIKEY header in all requests.

The API key is scoped to the user's client. All requests made with that key are limited to the data accessible by that client and role.

Multi-factor authentication (MFA)

Users can enable MFA for additional login security. When is_mfa_active is true, the user must complete a second authentication factor after providing their password.

MFA can be managed through:

The API — set is_mfa_active when creating or updating a user
The web portal — users can enable MFA in their account settings

Account locking

User accounts can become locked after repeated failed authentication attempts. A locked account (is_locked: true) cannot authenticate until an admin unlocks it.

State	`is_active`	`is_locked`	Can authenticate
Active	`true`	`false`	Yes
Locked	`true`	`true`	No — must be unlocked by admin
Deactivated	`false`	`false`	No — must be reactivated by admin

Password management

Users can update their own password with PATCH /v1/users/me/passwords. This requires the current password and the new password.

PATCH /v1/users/me/passwords

{
  "current_password": "OldPassword123!",
  "new_password": "NewSecurePassword456!"
}

Best practices

Use MFA for all users with administrative or financial access.
Apply least-privilege roles — assign the minimum role needed for each user's responsibilities.
Audit user accounts periodically — deactivate users who no longer need access.
Use separate users for each person — do not share user accounts or API keys.
Monitor locked accounts — repeated lockouts may indicate a brute-force attack.