# 

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

```mermaid
---
config:
  theme: 'neutral'
---
flowchart TD
    subgraph Reseller A
        RA_U1[User: admin@resellera.com]
        RA_U2[User: ops@resellera.com]
    end
    subgraph Merchant 1
        M1_U1[User: owner@merchant1.com]
        M1_U2[User: staff@merchant1.com]
    end
    subgraph Merchant 2
        M2_U1[User: owner@merchant2.com]
    end
    Reseller_A[Reseller A] --> Merchant_1[Merchant 1]
    Reseller_A --> Merchant_2[Merchant 2]
```

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

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

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

1. **Retrieve an API key**: `POST /v1/auth/keys` with `user_name` (email) and `password`.
2. **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.

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


## Further reading

* [About clients and resellers](/docs/concepts/account-hierarchy/clients-and-resellers)
* [About PCI-DSS compliance](/docs/concepts/security-compliance/pci-dss-overview)