> **Client contract note:** Apply [`shared/response-envelope.md`](../shared/response-envelope.md) to JSON responses after the response-contract release. Legacy wrapper examples below may reflect the prior API; the documented endpoint-specific payload fields are still useful. Not staging-verified.

# Access — Flutter / compatibility endpoints

**Source:** `alalmiyalhura/outlet`, `main`, `modules/Access/Routes/api.php`, `RoleController.php`, `SyncRolesRequest.php`, `SyncUserRolesHandler.php`.

**Scope clarification:** This module's two unprefixed routes are **legacy low-level role administration**, not normal Flutter customer features. Both require an authenticated caller with administrative permissions. The dashboard's current staff/role management APIs are documented separately in `dashboard/access.md`. A regular customer Flutter app must not expose these controls.

**API prefix:** `/api/v1` (route paths below). **Authentication:** `Authorization: Bearer <sanctum_token>`. **Success envelope:** `{ "data": ... }`.

## Route coverage

| Method | Endpoint | Middleware / authorization | Purpose |
|---|---|---|---|
| GET | `/roles` | `auth:sanctum`, `can:roles.manage` | Read all role names and their permission names |
| PUT | `/users/{userId}/roles` | `auth:sanctum`, `can:roles.manage`, `can:staff.manage` | Replace a user's role with exactly one permitted role |

## GET `/api/v1/roles`

Returns all roles, ordered by `name`, with their permissions. No body or query filters are read by the handler.

### Response — HTTP 200

| JSON path | Type | Nullable | Meaning |
|---|---|---|---|
| `data` | array<object> | No | All role records, sorted by name |
| `data[].name` | string | No | Role's stored name |
| `data[].permissions` | array<string> | No | Permission names granted to that role |

**Shape illustration** (role names are illustrative, not a claim about seeded database values):

```json
{
  "data": [
    {"name": "example-role", "permissions": ["roles.manage", "staff.manage"]}
  ]
}
```

The endpoint does not paginate. An empty database produces `{"data":[]}`. Access failures: `401 unauthenticated`, `403 forbidden`.

## PUT `/api/v1/users/{userId}/roles`

Requires `roles.manage` **and** `staff.manage`. Updates the target account under the same staff safeguards used by the dashboard role-change workflow. The handler deduplicates submitted roles, then requires exactly one **unique** role.

### Path and request body

| Field | Location | Type | Required | Rules |
|---|---|---|---|---|
| `userId` | path | positive integer | Yes | Numeric route parameter; identifies target user |
| `roles` | JSON body | array<string> | Yes (must be present) | `present|array`; domain requires exactly one unique role |
| `roles[]` | JSON body | string | For each element | Must exist in `roles.name` with `guard_name=web` |

```http
PUT /api/v1/users/42/roles
Authorization: Bearer <sanctum_token>
Content-Type: application/json

{"roles":["example-role"]}
```

### Response — HTTP 200

| JSON path | Type | Nullable | Meaning |
|---|---|---|---|
| `data` | object | No | Result wrapper |
| `data.roles` | array<string> | No | The single role name after the change |

```json
{"data":{"roles":["example-role"]}}
```

### Domain safeguards

- The input is **not** an unrestricted many-role sync. `[]` or two different roles returns `422 single_role_required`; duplicate identical entries collapse to one role before this check.
- A staff role is assigned only through `StaffAdministration::changeRole`, which enforces actor scope, target manageability, self-role-change restrictions, and protection of the last active super admin.
- A dashboard/staff role cannot be used here to promote a normal app account directly into dashboard access.
- For non-staff roles, the target must not be a staff account; otherwise `422 not_a_staff_role`.
- The role must exist for the `web` guard. The client should use the GET endpoint to show available names, but must still handle server rejection.

### Error contracts

| HTTP | Code | When |
|---|---|---|
| 401 | `unauthenticated` | No valid Sanctum session |
| 403 | `forbidden` | Caller lacks one or both required permissions |
| 422 | `validation_failed` | `roles` absent/not an array or item not a valid web-guard role |
| 422 | `single_role_required` | Not exactly one distinct role |
| 422 | `not_a_staff_role` | Non-staff role applied to staff account |
| Varies by domain exception | Access-specific code | Scope, protected-role, self-change, missing account, last-super-admin checks; use returned `error.code` and HTTP status |

Error envelope from Core:

```json
{
  "error": {
    "code": "single_role_required",
    "message": "A dashboard account holds exactly one role.",
    "request_id": null
  }
}
```

`message` is localized by `LocalizeAccessErrors`; English text above is a **shape example**. Validation errors can include `error.details` with field messages. Do not parse or hard-code localized message text.

## Flutter integration decision

These routes are **admin-only compatibility APIs**. For the customer Flutter application, mark the module **not applicable** unless an explicitly authorized staff experience is being built. Do not request `roles.manage` or `staff.manage` for customer sessions. Do not use these endpoints for customer account onboarding or permissions discovery.

## Verification

- **Code-level contract:** reviewed against routes, controller, request validation, application handler, exception classes, localization middleware and Core response wrapper on `main`.
- **Staging/runtime:** not executed; role database contents, exact localized wording and permission assignments are environment-dependent.
