> **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 API — Dashboard — Source-verified handoff

**Repository:** `alalmiyalhura/outlet`, `main`. **Base path:** `/api/v1`. **Scope:** all 27 Access routes (including compatibility aliases). **Verification:** source-level routes/controllers/presenters/StaffDirectory/settings policy; **not** live staging execution.

All authenticated endpoints use `Authorization: Bearer <token>`, and JSON requests use `Content-Type: application/json`. `ApiResponse::ok/created` returns an outer `data` object; list endpoints return `data`, `links`, `meta`. Error envelopes and handler-level business errors must be checked against Core and Access exception handling before claiming runtime-certified error codes.

## Shared response schemas

### StaffRow

| Field | Type | Description |
|---|---|---|
| `id` | integer | Staff user ID |
| `name/email/phone/username` | string|null | Identity fields |
| `role` | object|null | name, label |
| `status` | string | active or disabled |
| `status_label` | string | Localized status |
| `is_active` | boolean | Active staff |
| `account_status` | string | Underlying account state |
| `must_change_password` | boolean | Must change password |
| `last_login_at/created_at/deactivated_at` | ISO datetime|null | Timestamps |
| `deactivation_reason` | string|null | Reason |
| `is_self` | boolean | Is current viewer |
| `actions` | object | can_edit, can_change_role, can_deactivate, can_activate, can_reset_password |

### RoleRow

| Field | Type | Description |
|---|---|---|
| `name` | string | Role slug |
| `label` | string | Current localized label |
| `labels` | object | Localized label map |
| `description` | string|null | Current localized description |
| `descriptions` | object | Localized description map |
| `is_protected/all_permissions` | boolean | Role flags |
| `permissions` | string[] | Granted permissions |
| `permissions_count/accounts` | integer | Permission and staff counts |
| `created_at` | ISO datetime|null | Creation |
| `actions` | object | can_edit, can_delete, can_assign |

### AuditRow

| Field | Type | Description |
|---|---|---|
| `id` | integer | Audit ID |
| `event` | string | Audit event |
| `subject/subject_id` | string / integer | Audited entity |
| `old_values/new_values` | object|null | Changed fields |
| `actor` | object|null | id and name |
| `at` | ISO datetime|null | Event time |

### Example — login request / response

```json
{"login":"admin@example.com","password":"<password>","device_name":"dashboard"}
```

```json
{"data":{"token":"<redacted>","token_type":"Bearer","expires_at":"2026-11-22T16:00:00+00:00","session_ttl_minutes":120,"user":{"id":12,"name":"Example","email":"admin@example.com","phone":null,"locale":"en"},"staff":{"username":"admin","role":{"name":"admin","label":"Admin"},"status":"active","must_change_password":false,"must_change_password_text":null,"last_login_at":null},"roles":["admin"],"permissions":["staff.manage"],"menu":[]}}
```

Example values are illustrative; field shapes are derived from source.

### Example — paginated list envelope

```json
{"data":[],"links":{"first":"https://example.test/api/v1/admin/staff?page=1","last":"https://example.test/api/v1/admin/staff?page=1","prev":null,"next":null},"meta":{"current_page":1,"from":null,"last_page":1,"per_page":25,"to":null,"total":0}}
```

## `POST /api/v1/admin/auth/login`

**Authorization:** Public; `throttle:auth`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `login` | string | Required unless username/email/phone supplied; max 190 |
| `username` | string | Optional; max 190 |
| `email` | string | Optional; max 190 |
| `phone` | string | Optional; max 30 |
| `password` | string | Required; max 255 |
| `device_name` | string | Optional; max 100; default dashboard |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `token` | string | Sanctum bearer token |
| `token_type` | string | Bearer |
| `expires_at` | ISO datetime | Token expiry |
| `session_ttl_minutes` | integer | Session TTL |
| `user.id` | integer | User ID |
| `user.name` | string|null | Display name |
| `user.email` | string|null | Email |
| `user.phone` | string|null | Phone |
| `user.locale` | string|null | Locale |
| `staff.username` | string|null | Dashboard username |
| `staff.role` | object|null | Role name and localized label |
| `staff.status` | string | active or disabled |
| `staff.must_change_password` | boolean | Password-change requirement |
| `staff.must_change_password_text` | string|null | Localized warning |
| `staff.last_login_at` | ISO datetime|null | Last sign-in |
| `roles` | string[] | Assigned roles |
| `permissions` | string[] | Effective permission codes |
| `menu` | object[] | Visible menu sections with localized labels |

Either `login` or one alternative identifier is required. Never log the token or password.


## `POST /api/v1/auth/admin/login`

**Authorization:** Public; alias; `throttle:auth`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `login / username / email / phone` | string | Same rules as primary login |
| `password` | string | Required; max 255 |
| `device_name` | string | Optional; max 100 |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `token/token_type/expires_at/session_ttl_minutes` | mixed | Same as primary login |
| `user/staff/roles/permissions/menu` | mixed | Same as primary login |

Exact alias of `/api/v1/admin/auth/login`.


## `POST /api/v1/admin/auth/logout`

**Authorization:** Bearer token. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| — | — | No request body; use bearer authentication where applicable. |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `message` | string | Localized signed-out confirmation |

Deletes the current bearer token, not necessarily all sessions.


## `GET /api/v1/admin/me`

**Authorization:** Bearer token; must have staff permissions. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| — | — | No request body; use bearer authentication where applicable. |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `user.id` | integer | User ID |
| `user.name` | string|null | Display name |
| `user.email` | string|null | Email |
| `user.phone` | string|null | Phone |
| `user.locale` | string|null | Locale |
| `staff.username` | string|null | Dashboard username |
| `staff.role` | object|null | Role name and localized label |
| `staff.status` | string | active or disabled |
| `staff.must_change_password` | boolean | Password-change requirement |
| `staff.must_change_password_text` | string|null | Localized warning |
| `staff.last_login_at` | ISO datetime|null | Last sign-in |
| `roles` | string[] | Assigned roles |
| `permissions` | string[] | Effective permission codes |
| `menu` | object[] | Visible menu sections with localized labels |
| `session_expires_at` | ISO datetime|null | Current token expiry |

App-only users receive `not_staff` (403).


## `POST /api/v1/admin/me/password`

**Authorization:** Bearer token; `throttle:auth`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `current_password` | string | Required; max 255 |
| `password` | string | Required; confirmed; different from current; StaffPassword rule |
| `password_confirmation` | string | Required by confirmed validation |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `message` | string | Localized success message |

Password policy is delegated to `StaffPassword::rule()`; do not assume a fixed minimum here.


## `GET /api/v1/admin/staff`

**Authorization:** Bearer + `staff.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `per_page` | integer | Optional; 1–100; default 25 |
| `sort` | string | id,name,created_at,last_login_at,role; optional - prefix |
| `filter.role` | string | Optional; comma-separated role names; max 500 |
| `filter.active` | boolean-like | 0,1,true,false |
| `filter.search` | string | Max 100 |
| `filter.last_login_from/to` | YYYY-MM-DD | Optional |
| `filter.never_signed_in` | boolean-like | 0,1,true,false |
| `filter.created_from/to` | YYYY-MM-DD | Optional |
| `filter.must_change_password` | boolean-like | 0,1,true,false |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `data` | array | Rows |
| `links` | object | first, last, prev, next URLs |
| `meta` | object | current_page, from, last_page, per_page, to, total |
| `data[]` | StaffRow | See shared StaffRow contract below |
| `meta.counts` | object | all, active, disabled |
| `meta.filters` | object | role choices and active values |
| `meta.sorts` | string[] | Allowed sort keys |

Default sort is `-created_at`.


## `POST /api/v1/admin/staff`

**Authorization:** Bearer + `staff.manage`. **Success:** HTTP 201.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `name` | string | Required; 2–120 |
| `email` | email | Required without phone; nullable; max 190 |
| `phone` | string | Required without email; nullable; max 30 |
| `username` | string|null | Optional; max 30 |
| `password` | string|null | Optional; StaffPassword rule |
| `role` | string | Required; max 125 |
| `locale` | string|null | Enabled locale |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Staff user ID |
| `name/email/phone/username` | string|null | Identity fields |
| `role` | object|null | name, label |
| `status` | string | active or disabled |
| `status_label` | string | Localized status |
| `is_active` | boolean | Active staff |
| `account_status` | string | Underlying account state |
| `must_change_password` | boolean | Must change password |
| `last_login_at/created_at/deactivated_at` | ISO datetime|null | Timestamps |
| `deactivation_reason` | string|null | Reason |
| `is_self` | boolean | Is current viewer |
| `actions` | object | can_edit, can_change_role, can_deactivate, can_activate, can_reset_password |
| `locale` | string | Staff locale |
| `permissions` | object | Permission matrix |
| `active_sessions` | array | Sessions |
| `recent_history/recent_activity` | array | Latest audits |
| `temporary_password` | string|null | Generated password if applicable |
| `temporary_password_note` | string|null | Localized note |

Returns detailed staff record plus temporary password if generated; expose password once only.


## `GET /api/v1/admin/staff/{userId}`

**Authorization:** Bearer + `staff.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `userId` | integer | Required path; numeric |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Staff user ID |
| `name/email/phone/username` | string|null | Identity fields |
| `role` | object|null | name, label |
| `status` | string | active or disabled |
| `status_label` | string | Localized status |
| `is_active` | boolean | Active staff |
| `account_status` | string | Underlying account state |
| `must_change_password` | boolean | Must change password |
| `last_login_at/created_at/deactivated_at` | ISO datetime|null | Timestamps |
| `deactivation_reason` | string|null | Reason |
| `is_self` | boolean | Is current viewer |
| `actions` | object | can_edit, can_change_role, can_deactivate, can_activate, can_reset_password |
| `locale` | string | Staff locale |
| `created_by/deactivated_by` | object|null | Actor id/name |
| `active_sessions` | array | Active sessions |
| `permissions` | object | Permission matrix |
| `recent_history/recent_activity` | array | Latest 10 audit rows each |
| `links` | object | history, activity URLs |




## `PATCH /api/v1/admin/staff/{userId}`

**Authorization:** Bearer + `staff.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `name` | string | Optional; 2–120 |
| `email` | email | Optional; max 190 |
| `phone` | string | Optional; max 30 |
| `username` | string|null | Optional; max 30; null clears |
| `locale` | string | Optional; enabled locale |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Staff user ID |
| `name/email/phone/username` | string|null | Identity fields |
| `role` | object|null | name, label |
| `status` | string | active or disabled |
| `status_label` | string | Localized status |
| `is_active` | boolean | Active staff |
| `account_status` | string | Underlying account state |
| `must_change_password` | boolean | Must change password |
| `last_login_at/created_at/deactivated_at` | ISO datetime|null | Timestamps |
| `deactivation_reason` | string|null | Reason |
| `is_self` | boolean | Is current viewer |
| `actions` | object | can_edit, can_change_role, can_deactivate, can_activate, can_reset_password |

Partial update; returns fresh StaffRow.


## `PUT /api/v1/admin/staff/{userId}/role`

**Authorization:** Bearer + `staff.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `role` | string | Required; max 125 |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Staff user ID |
| `name/email/phone/username` | string|null | Identity fields |
| `role` | object|null | name, label |
| `status` | string | active or disabled |
| `status_label` | string | Localized status |
| `is_active` | boolean | Active staff |
| `account_status` | string | Underlying account state |
| `must_change_password` | boolean | Must change password |
| `last_login_at/created_at/deactivated_at` | ISO datetime|null | Timestamps |
| `deactivation_reason` | string|null | Reason |
| `is_self` | boolean | Is current viewer |
| `actions` | object | can_edit, can_change_role, can_deactivate, can_activate, can_reset_password |
| `changed` | boolean | False when role already assigned |

Cannot change own role; protected super-admin restrictions apply.


## `POST /api/v1/admin/staff/{userId}/deactivate`

**Authorization:** Bearer + `staff.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `reason` | string|null | Optional; max 300 |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Staff user ID |
| `name/email/phone/username` | string|null | Identity fields |
| `role` | object|null | name, label |
| `status` | string | active or disabled |
| `status_label` | string | Localized status |
| `is_active` | boolean | Active staff |
| `account_status` | string | Underlying account state |
| `must_change_password` | boolean | Must change password |
| `last_login_at/created_at/deactivated_at` | ISO datetime|null | Timestamps |
| `deactivation_reason` | string|null | Reason |
| `is_self` | boolean | Is current viewer |
| `actions` | object | can_edit, can_change_role, can_deactivate, can_activate, can_reset_password |
| `changed` | boolean | False on repeat |

Deactivation revokes staff sessions; cannot deactivate self or final active super-admin.


## `POST /api/v1/admin/staff/{userId}/activate`

**Authorization:** Bearer + `staff.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| — | — | No request body; use bearer authentication where applicable. |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Staff user ID |
| `name/email/phone/username` | string|null | Identity fields |
| `role` | object|null | name, label |
| `status` | string | active or disabled |
| `status_label` | string | Localized status |
| `is_active` | boolean | Active staff |
| `account_status` | string | Underlying account state |
| `must_change_password` | boolean | Must change password |
| `last_login_at/created_at/deactivated_at` | ISO datetime|null | Timestamps |
| `deactivation_reason` | string|null | Reason |
| `is_self` | boolean | Is current viewer |
| `actions` | object | can_edit, can_change_role, can_deactivate, can_activate, can_reset_password |
| `changed` | boolean | False on repeat |




## `POST /api/v1/admin/staff/{userId}/reset-password`

**Authorization:** Bearer + `staff.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `password` | string|null | Optional; StaffPassword rule; omitted generates temporary |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `id` | integer | Staff user ID |
| `name/email/phone/username` | string|null | Identity fields |
| `role` | object|null | name, label |
| `status` | string | active or disabled |
| `status_label` | string | Localized status |
| `is_active` | boolean | Active staff |
| `account_status` | string | Underlying account state |
| `must_change_password` | boolean | Must change password |
| `last_login_at/created_at/deactivated_at` | ISO datetime|null | Timestamps |
| `deactivation_reason` | string|null | Reason |
| `is_self` | boolean | Is current viewer |
| `actions` | object | can_edit, can_change_role, can_deactivate, can_activate, can_reset_password |
| `changed` | boolean | Action indicator |
| `temporary_password` | string|null | Generated password, returned once |
| `temporary_password_note` | string|null | Localized note |

Cannot reset own password through staff administration; use `/admin/me/password`.


## `GET /api/v1/admin/staff/{userId}/history`

**Authorization:** Bearer + `staff.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `per_page` | integer | Optional; 1–100; default 25 |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `data` | array | Rows |
| `links` | object | first, last, prev, next URLs |
| `meta` | object | current_page, from, last_page, per_page, to, total |
| `data[]` | AuditRow | See AuditRow contract |

History of changes to this staff account.


## `GET /api/v1/admin/staff/{userId}/activity`

**Authorization:** Bearer + `staff.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `per_page` | integer | Optional; 1–100; default 25 |
| `filter.event` | string | Optional; max 60 |
| `filter.subject` | string | Optional; max 60 |
| `filter.from/to` | YYYY-MM-DD | Optional |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `data` | array | Rows |
| `links` | object | first, last, prev, next URLs |
| `meta` | object | current_page, from, last_page, per_page, to, total |
| `data[]` | AuditRow | See AuditRow contract |

Activity is actions performed by staff across modules; history is changes to staff account.


## `GET /api/v1/admin/permissions`

**Authorization:** Bearer + `roles.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| — | — | No request body; use bearer authentication where applicable. |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `sections` | array | Localized permission matrix grouped by section |
| `total` | integer | Number of permissions |




## `GET /api/v1/admin/roles`

**Authorization:** Bearer + `roles.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `filter.search` | string | Optional; max 100 |
| `filter.protected` | 0|1 | Optional |
| `filter.permission` | string | Optional; max 100 |
| `filter.in_use` | 0|1 | Optional |
| `sort` | string | name,created_at,accounts; optional - prefix |
| `per_page` | integer | 1–100; default 50 |
| `page` | integer | Page number |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `data` | array | Rows |
| `links` | object | first, last, prev, next URLs |
| `meta` | object | current_page, from, last_page, per_page, to, total |
| `data[]` | RoleRow | See RoleRow contract |




## `POST /api/v1/admin/roles`

**Authorization:** Bearer + `roles.manage`. **Success:** HTTP 201.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `name` | string | Required; max 40 |
| `label` | object | Required localized map; each max 80 |
| `description` | object|null | Optional localized map; each max 300 |
| `permissions` | string[] | Required present; distinct; each max 100 |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `name` | string | Role slug |
| `label` | string | Current localized label |
| `labels` | object | Localized label map |
| `description` | string|null | Current localized description |
| `descriptions` | object | Localized description map |
| `is_protected/all_permissions` | boolean | Role flags |
| `permissions` | string[] | Granted permissions |
| `permissions_count/accounts` | integer | Permission and staff counts |
| `created_at` | ISO datetime|null | Creation |
| `actions` | object | can_edit, can_delete, can_assign |
| `matrix` | array | Role permission matrix |
| `accounts_preview` | array | Up to 10 assigned accounts |
| `recent_history` | array | Latest audit events |
| `links` | object | history, accounts URLs |

RoleAdministration enforces protected-role and permission-scope rules.


## `GET /api/v1/admin/roles/{name}`

**Authorization:** Bearer + `roles.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `name` | slug | Path; lowercase a-z, 0-9, hyphen |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `name` | string | Role slug |
| `label` | string | Current localized label |
| `labels` | object | Localized label map |
| `description` | string|null | Current localized description |
| `descriptions` | object | Localized description map |
| `is_protected/all_permissions` | boolean | Role flags |
| `permissions` | string[] | Granted permissions |
| `permissions_count/accounts` | integer | Permission and staff counts |
| `created_at` | ISO datetime|null | Creation |
| `actions` | object | can_edit, can_delete, can_assign |
| `matrix` | array | Permission matrix |
| `accounts_preview` | array | Up to 10 assigned users |
| `recent_history` | array | Up to 10 audit rows |
| `links` | object | history and accounts URLs |




## `PATCH /api/v1/admin/roles/{name}`

**Authorization:** Bearer + `roles.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `name` | — | Prohibited |
| `label` | object | Optional localized map; each max 80 |
| `description` | object|null | Optional; each max 300 |
| `permissions` | string[] | Optional; distinct; each max 100 |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `name` | string | Role slug |
| `label` | string | Current localized label |
| `labels` | object | Localized label map |
| `description` | string|null | Current localized description |
| `descriptions` | object | Localized description map |
| `is_protected/all_permissions` | boolean | Role flags |
| `permissions` | string[] | Granted permissions |
| `permissions_count/accounts` | integer | Permission and staff counts |
| `created_at` | ISO datetime|null | Creation |
| `actions` | object | can_edit, can_delete, can_assign |
| `matrix` | array | Permission matrix |
| `changed` | boolean | True when updated |

Omitted label, description and permissions retain existing values.


## `DELETE /api/v1/admin/roles/{name}`

**Authorization:** Bearer + `roles.manage`. **Success:** HTTP 204.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| — | — | No request body; use bearer authentication where applicable. |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| — | — | Empty success body. |

Protected roles and roles in use cannot be deleted.


## `GET /api/v1/admin/roles/{name}/history`

**Authorization:** Bearer + `roles.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `per_page` | integer | 1–100; default 25 |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `data` | array | Rows |
| `links` | object | first, last, prev, next URLs |
| `meta` | object | current_page, from, last_page, per_page, to, total |
| `data[]` | AuditRow | Role change history |




## `GET /api/v1/admin/access/settings`

**Authorization:** Bearer + `settings.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| — | — | No request body; use bearer authentication where applicable. |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `session_ttl_minutes` | integer | 15–43200 |
| `login_max_attempts` | integer | 3–20 |
| `login_lockout_minutes` | integer | 1–1440 |
| `temporary_password_length` | integer | 10–64 |
| `limits` | object | Min/max values for each setting |




## `PATCH /api/v1/admin/access/settings`

**Authorization:** Bearer + `settings.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `session_ttl_minutes` | integer | Optional; 15–43200 |
| `login_max_attempts` | integer | Optional; 3–20 |
| `login_lockout_minutes` | integer | Optional; 1–1440 |
| `temporary_password_length` | integer | Optional; 10–64 |
| `reason` | string|null | Optional; max 300 |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `session_ttl_minutes` | integer | Current setting |
| `login_max_attempts` | integer | Current setting |
| `login_lockout_minutes` | integer | Current setting |
| `temporary_password_length` | integer | Current setting |
| `limits` | object | Min/max per setting |

Changes are audited.


## `GET /api/v1/admin/access/settings/history`

**Authorization:** Bearer + `settings.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `per_page` | integer | 1–100; default 25 |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `data` | array | Rows |
| `links` | object | first, last, prev, next URLs |
| `meta` | object | current_page, from, last_page, per_page, to, total |
| `data[]` | AuditRow | Settings audit events |




## `GET /api/v1/roles`

**Authorization:** Bearer + `roles.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| — | — | No request body; use bearer authentication where applicable. |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `data[]` | object | name string, permissions string[] |

Compatibility endpoint; unlike dashboard roles listing this is an unpaginated role collection.


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

**Authorization:** Bearer + `roles.manage` and `staff.manage`. **Success:** HTTP 200.

### Request contract

| Field | Type | Required / validation |
|---|---|---|
| `userId` | integer | Numeric path |
| `roles` | string[] | Required; validation delegated to SyncRolesRequest |

### Response contract (`data` unless otherwise stated)

| Field | Type | Meaning |
|---|---|---|
| `roles` | string[] | Resulting assigned roles |

Compatibility endpoint; handler enforces staff role assignment rules.

## Source evidence and quality boundary

- `modules/Access/Routes/api.php` — method, path, middleware and permissions.
- `modules/Access/Interfaces/Http/Controllers/Admin/{AdminAuthController,StaffController,RoleAdminController,AccessSettingsController}.php` — validation, response composition and status.
- `modules/Access/Interfaces/Http/Controllers/RoleController.php` — compatibility endpoints.
- `modules/Access/Interfaces/Http/Presenters/{StaffSessionView,StaffView,AdminPage}.php` — response shapes.
- `modules/Access/Infrastructure/ReadModel/StaffDirectory.php` — staff filters and sorting.
- `modules/Access/Infrastructure/Settings/SettingsAccessPolicy.php` — access settings limits.

### Verified supplemental contracts — password, role synchronization and security errors

These rules were checked directly against the relevant request classes, application services and middleware on `main`.

**Staff password validation** (`StaffPassword::rule()`): required when changing one's own password; optional on staff creation and admin reset. Password must contain **letters and numbers**, length at least `IdentityPolicy::passwordPolicy()->minLength` (configured dynamically) and at most **255** characters. **Mixed case** is additionally required only when `requiresMixedCase` is true. Do not hardcode the minimum length in the dashboard; retrieve platform policy when exposed or show the server's 422 validation message. For `POST /admin/me/password`, `password_confirmation` must match `password` and the new password must differ from `current_password`.

**Compatibility role synchronization** (`PUT /api/v1/users/{userId}/roles`): `roles` must be **present** and an **array**; every `roles.*` must be a string and must exist in the `roles` table with `guard_name=web`. The handler applies the staff role-assignment restrictions; the route additionally requires both `roles.manage` and `staff.manage`. A present empty array passes the request's structural validation, but the domain handler may reject an invalid assignment; do not assume that clearing all roles is supported.

**Access security business errors** (`LocalizeAccessErrors`): business errors are returned under `error`, with `error.message` translated using the request locale. Additional response details are conditionally present:

| Condition | Response addition | Client behavior |
|---|---|---|
| Admin login locked | `error.details.retry_after_seconds`: integer; `Retry-After` HTTP header | Disable retry until lock expires |
| Role assigned to accounts | `error.details.accounts`: integer | Show affected-account count before attempting deletion |
| Unknown permission / permission scope exceeded | `error.details.permissions`: string[] | Show invalid/out-of-scope permissions |
| Account banned or suspended | `error.details.kind`: `ban` or `suspension` | Explain blocked login; `account_banned` is used for banned accounts |

**Confirmed domain invariants**: deactivation revokes every active session; reset-password revokes all sessions and returns a generated temporary password only once when no password was supplied; repeated activate/deactivate/change-role requests are no-ops when no change is needed. A role cannot be deleted while assigned to staff or if protected. Adding permissions beyond the actor's scope is prohibited. The last active super admin cannot be deactivated or reassigned, and an administrator cannot change their own role or deactivate themselves through staff management.

**Additional reviewed sources:** `modules/Access/Interfaces/Http/Requests/{StaffPassword,SyncRolesRequest}.php`, `modules/Access/Interfaces/Http/Middleware/LocalizeAccessErrors.php`, `modules/Access/Application/{Roles/RoleAdministration,Staff/StaffAdministration}.php`.

**Remaining verification boundary:** the exact nested permission matrix from `AccessTexts::matrix`, numeric HTTP statuses for all domain exceptions as rendered by Core, the live `IdentityPolicy` minimum password length, and staging integration tests are not independently verified here. Route and static request contracts are documented; do not call this module runtime-certified yet.
