Supervisor Creation

Overview

A supervisor is a user created by a store that has read-only access to a defined set of branches and their activity. Each supervisor is independent — it has its own user account and credentials, separate from the store that created it.

A supervisor can be assigned to multiple branches, and a branch can have multiple supervisors. By default, supervisors can only read information; additional capabilities can be unlocked by the store via operational flags.

When a supervisor is created, three things happen simultaneously:

• A new supervisor entity is registered and associated with the creating store
• A new user is created using the provided email address
• A new account under this user is created with the supervisor role

⚠️ This user represents the supervisor and operates independently — it has its own credentials and access token, separate from the store that created it.

---

Default Access

By default, a supervisor has read-only access to:

• Their assigned branches and the payment orders those branches created
• The store that owns them and the payment orders that store created

No write or operational capabilities are granted unless explicitly enabled via flags (see Operational Flags below).

---

Endpoint

POST /supervisor

Full API reference: Create a new supervisor

---

Authentication

This endpoint requires a valid Bearer Token issued to a user with the store role.

Authorization: Bearer <your_access_token>

Requests from users without the store role will be rejected.

See the Authentication Guide for details on obtaining a token.

---

Request Example

curl -X POST "/api/v1/supervisor" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
    "name": "John Doe",
    "email": "john.doe@example.com"
  }'

Request Body

Field	Type	Required	Description
name	string	Yes	Full name of the supervisor
email	string	Yes	Email address used to create the user account

---

Assigning Branches

Branches are assigned to a supervisor via a dedicated endpoint. The request replaces the current assignment list entirely — branches included are assigned, branches previously assigned but omitted are unassigned and lose any permissions granted through the supervisor.

PATCH /supervisor/branches

Full API reference: Assign or unassign branches to a supervisor

curl -X PATCH "/api/v1/supervisor/branches" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
    "id": "30de85c9-7c64-45c5-97da-b1d7c537203d",
    "branchIds": [
      "11649862-4f25-4c98-8225-71dfc634f4b2"
    ]
  }'

Field	Type	Required	Description
id	UUID	Yes	ID of the supervisor
branchIds	UUID[]	Yes	Full list of branch IDs to assign

⚠️ Sending an empty branchIds array removes all branch assignments from the supervisor.

---

Operational Flags

The store can expand a supervisor's capabilities by updating its operational flags. Only the flags included in the request are modified; omitted flags keep their current values.

PATCH /supervisor/flags

Full API reference: Update supervisor flags

curl -X PATCH "/api/v1/supervisor/flags" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your_access_token>" \
  -d '{
    "id": "30de85c9-7c64-45c5-97da-b1d7c537203d",
    "qrActive": true,
    "buyUsdtActive": false
  }'

Flag	Type	Default	Description
qrActive	boolean	false	Allows the supervisor to read the store's QR code
buyUsdtActive	boolean	false	Allows the supervisor to perform USDT extraction operations using the store's wallet

---

Next Steps

After the supervisor is created, the supervisor user must complete the authentication process independently before making any API requests.

1. The supervisor user follows the Authentication Guide
2. Upon successful authentication, the supervisor user receives their own access token
3. All subsequent requests made by the supervisor must use that token — not the store's token

---

Important Notes

• Only users with the store role can create supervisors and manage their flags and branch assignments
• Each supervisor operates independently with its own credentials and session
• Access tokens are not shared between store and supervisor users
• A supervisor can be assigned to multiple branches, and a branch can have multiple supervisors
• Branch assignment via PATCH /supervisor/branches is a full replacement — always send the complete desired list