User Permissions#

Configure user roles and permissions.

Permissions are dot-notation keys such as transactions.view, transactions.refund or users.manage. A member's access comes from their role; individual members can additionally have per-user overrides. All endpoints require Authorization: Bearer <JWT>.

Merchant Roles#

Every merchant has three built-in roles:

Code	Name	Editable	Location scope
`merchant_owner`	Merchant Owner	No (protected)	All locations
`merchant_admin`	Merchant Admin	Yes	All locations
`merchant_staff`	Merchant Staff	Yes	Assigned locations only

A merchant edits its own copy of a role: changes reach only that merchant's team. Resetting a role returns it to the platform default.

Get Permission Catalog#

GET/api/v1/roles/permissions

Any authenticated user. Returns every permission key, grouped by area, plus the resource × action matrix the Roles & Permissions screen renders.

Response (excerpt):

Get Permission Catalogjson

{
  "success": true,
  "data": {
    "all": ["transactions.view", "transactions.create", "transactions.refund", "users.view", "users.manage"],
    "grouped": {
      "transactions": ["transactions.view", "transactions.create", "transactions.refund"],
      "users": ["users.view", "users.manage"]
    },
    "matrix": [],
    "sensitive": ["users.manage"],
    "presets": { "fullAccess": [], "operations": [], "readOnly": [] }
  }
}

Get Merchant Roles#

GET/api/v1/roles/merchant

Requires users.view in the caller's merchant. Returns the merchant's roles and what each one grants.

Response (excerpt):

Get Merchant Rolesjson

{
  "success": true,
  "data": {
    "matrix": [],
    "total": 48,
    "canManage": true,
    "actorPermissions": ["transactions.view", "transactions.refund"],
    "overrideRestricted": ["users.manage"],
    "roles": [
      {
        "id": "6a2d9f4e-3b1c-4e7a-8d5f-0c9b2e1a7f36",
        "code": "merchant_staff",
        "name": "Merchant Staff",
        "description": "Default role with the approved least-privilege operational access.",
        "permissions": ["transactions.view", "transactions.create"],
        "defaultPermissions": ["transactions.view", "transactions.create"],
        "userCount": 4,
        "activeUserCount": 3,
        "locationScope": "assigned",
        "isProtected": false,
        "canEdit": true,
        "isCustomized": false
      }
    ]
  }
}

Update Role Permissions#

PUT/api/v1/roles/merchant/:code

Requires users.manage. :code is merchant_admin or merchant_staff; merchant_owner returns 403.

Update Role Permissionsbash

curl -X PUT https://uat.auxcore.net/api/v1/roles/merchant/merchant_staff \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permissions": ["transactions.view", "transactions.create", "transactions.refund", "reports.view"]
  }'

permissions must be an array of merchant permission keys. An unknown key returns 400 (Not a merchant permission: ...).
Granting an action adds its .view permission automatically. At least one permission is required.
You cannot grant a permission you do not hold yourself (403).

Response: 200 OK with the updated role object (same shape as an entry in roles above, isCustomized: true).

Reset Role Permissions#

DELETE/api/v1/roles/merchant/:code

Requires users.manage. Removes the merchant's customisation; the role goes back to the platform default. Returns the role object with isCustomized: false.

Per-User Overrides#

To give one member more or less than their role, send permissionOverrides when creating or updating the user (see Merchant Users):

PUT/api/v1/users/:userId

Per-User Overridesjson

{
  "permissionOverrides": {
    "granted": ["transactions.void"],
    "revoked": ["reports.export"]
  }
}

Requires users.manage. You cannot change your own permissions.
Only merchant permission keys are allowed, and sensitive keys (listed in overrideRestricted) can only come from a role.
A Merchant Owner cannot have overrides. "permissionOverrides": null removes them.

Roles API (Admin)#

Tenant admins manage the platform role catalogue with:

http

GET /api/v1/roles
POST /api/v1/roles
GET /api/v1/roles/:id
PUT /api/v1/roles/:id
DELETE /api/v1/roles/:id

Reading requires users.view (list) or an admin role (single role). Creating, updating or deleting a role requires an admin role and users.manage.

Need help? Contact support@auxcore.net