# 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

```http
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):**

```json
{
  "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

```http
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):**

```json
{
  "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

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

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

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

```http
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](./users.md)):

```http
PUT /api/v1/users/:userId
```

```json
{
  "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