Docyrus Api Dev

# ACL Endpoints for Frontend Developers

Base path: `/api/v1/users/acl`

All ACL endpoints require the normal authenticated API session.

These endpoints may be hidden from generated Swagger/OpenAPI output because the backend currently marks them with `@ApiExcludeEndpoint()`. Treat this document as the frontend integration source of truth and call these routes directly with `RestApiClient` or `useDocyrusClient()`.

## Important identifier rules

- Role assignments and ACL role relations are stored using `tenant_role.uid`.
- Returned nested role objects expose both `id` and `uid`, and both values map to the role UID.
- For role operations, backend can resolve incoming `roleId` values against both `tenant_role.uid` and `tenant_role.id`, but frontend apps should prefer role `uid` values from API responses.
- For user-role writes and role-query `roleIds`, send role UUIDs and prefer UID values.
- `tenant_role_query.query` is a JSON object matching the app's filter-query structure. Send raw JSON, not stringified JSON.

## Enum values

### Role ownership

- `APP`
- `CUSTOM`
- `PRODUCT`
- `SYSTEM`
- `USER`

### Role query restriction level

- `hidden`
- `read-only`
- `not-deletable`

## Endpoint groups

### 1) Record ACL endpoints

These manage record-level shares, not role CRUD.

| Method | Path | Purpose |
| :----- | :--- | :------ |
| `GET` | `/v1/users/acl?dataSourceId={uuid}&recordId={uuid}` | Fetch direct and effective ACL rows for a record |
| `POST` | `/v1/users/acl/share` | Upsert record share rows |
| `DELETE` | `/v1/users/acl/share` | Revoke matching share rows |
| `PUT` | `/v1/users/acl/owner` | Transfer record ownership |

#### Share payload notes

- `principalType` must be one of: `user`, `team`, `role`, `tenant`, `public`.
- `permissions` is the backend ACL bitmask value.
- `expiresAt` is optional and must be a valid ISO date if provided.

#### Record ACL response shapes

`GET /v1/users/acl` returns:

```json
{
  "direct": [
    {
      "id": "uuid",
      "principal_type": "user",
      "principal_id": "uuid",
      "permissions": 7,
      "expires_at": null,
      "created_by": "uuid-or-null",
      "created_on": "2026-03-29T20:10:00.000Z"
    }
  ],
  "effective": [
    {
      "id": "uuid",
      "user_id": "uuid",
      "permissions": 7,
      "source_principal_type": "role",
      "source_principal_id": "uuid"
    }
  ]
}
```

### 2) Role endpoints

| Method | Path | Purpose |
| :----- | :--- | :------ |
| `GET` | `/v1/users/acl/roles` | List tenant roles |
| `GET` | `/v1/users/acl/roles/:roleId` | Get one role |
| `POST` | `/v1/users/acl/roles` | Create role |
| `PATCH` | `/v1/users/acl/roles/:roleId` | Partial update role |
| `DELETE` | `/v1/users/acl/roles/:roleId` | Hard delete role |

#### Role create/update rules

- `slug` is required on create and must be unique within the tenant.
- Create defaults:
  - `ownership = "CUSTOM"`
  - `privileges = ""`
  - `status = 1`
- Role responses include both `id` and `uid`, both pointing to the role UID.

#### Role delete side effects

Deleting a role also cleans up dependent ACL state:

- removes `tenant_user_role` assignments for that role
- sets `tenant_user.primary_role` to `null` where applicable
- removes linked `tenant_acl_rule` rows
- removes linked `tenant_acl_field_rule` rows
- removes the role from `tenant_role_query` role arrays
- hard deletes role-query rows that become empty after role removal

Frontend implication: after role deletion, refresh role lists, user-role lists, role-query lists, and any UI showing primary-role labels.

### 3) User-role endpoints

| Method | Path | Purpose |
| :----- | :--- | :------ |
| `GET` | `/v1/users/acl/user-roles` | List assignments across the tenant |
| `GET` | `/v1/users/acl/users/:userId/roles` | List assignments for one user |
| `POST` | `/v1/users/acl/users/:userId/roles` | Add roles to a user |
| `PUT` | `/v1/users/acl/users/:userId/roles` | Replace the full role set for a user |
| `DELETE` | `/v1/users/acl/users/:us