ACL

The Access Control List (ACL) module manages roles, permissions, and role assignments to users. The AclController is mounted at /acl and restricted to UserType.MORIA & UserType.ORGANIZATION via a controller-level @Roles guard. Each endpoint is also protected by specific @Permissions(...) — FE must ensure the logged-in admin holds a role that has granted those permissions.

Property	Value
Base URL	{HOST}/v1
Auth	Bearer JWT (header Authorization) or cookie access_token
Content-Type	application/json
Error envelope	{ "message": string | string[], "statusCode": number, "error": string }
Validation	Global ValidationPipe · whitelist: true, forbidNonWhitelisted: true · unknown field → 400
Related modules	users, organizations, authentication, onboarding
Document version	v1 · 2026-05-20
Audience	Internal FE devs (mobile + web)

Summary

A MORIA or ORGANIZATION admin can create a custom role for their organization, set a combination of permissions, and assign it to users. The endpoints are split into two groups: roles (/acl/roles) and permissions (/acl/permissions). Assign/unassign operations on a user’s role use the /acl/assign-role endpoint via the unassign_role flag.

Method	Path	Auth	Summary
POST	/v1/acl/roles	bearer	Create a new role for the organization
GET	/v1/acl/roles	bearer	List roles with role_type / user_type filters
GET	/v1/acl/roles/:role_id	bearer	Detail of one role
PATCH	/v1/acl/roles/:role_id	bearer	Update role fields or reset the permission list
DELETE	/v1/acl/roles/:role_id	bearer	Delete a role
PATCH	/v1/acl/assign-role	bearer	Assign / unassign a role to a user
GET	/v1/acl/permissions	bearer	List all available permissions
GET	/v1/acl/permissions/:permission_id	bearer	Detail of one permission
GET	/v1/acl/roles/:role_id/permissions	bearer	List permissions held by a role
DELETE	/v1/acl/roles/:role_id/permissions	bearer	Detach permissions from a role

Auth + scope notes

• All controller-level endpoints are gated by @Roles(MORIA, ORGANIZATION) — INDIVIDUAL users always get 403.
• For create role: a moria_admin must send the target organization_id. A regular organization admin may only create a role for their own organization (the server compares with admin.organization.id).
• For list role: MORIA can read across organizations (filter via organization_id in the query); ORGANIZATION is always scoped to its own organization.
• Permission strings (e.g. create-role, read-permission) are used as-is — no translation needed.

---

POST /v1/acl/roles bearer

Create a new role together with the list of permissions to be attached. For a regular organization admin, the organization_id in the body must match the caller’s organization — otherwise the response is 403 Forbidden.

bearer MORIA, ORGANIZATION create-role RESOURCE_CREATED

Request body — CreateRoleDto

Field	Type	Required	Notes
name	string	✓	Unique role name (e.g. organization_admin)
description	string	✓	Short role description
organization_id	string (UUID)	optional	Required when sent by a moria_admin; for an organization admin must match their organization
permissions	string[]	✓	List of permission names to be assigned (e.g. ["update-role", "read-role", "invite-individual-user"])

Example request

{
  "name": "organization_admin",
  "description": "This is the organization admin role",
  "organization_id": "03be5259-f281-478e-a8d0-e7e825e525f2",
  "permissions": [
    "update-role",
    "read-role",
    "delete-role",
    "invite-individual-user",
    "invite-organization-admin"
  ]
}

Response — 201 Created

{
  "status": "success",
  "statusCode": 201,
  "message": "role created successfully",
  "data": {
    "role": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "organization_admin",
      "display_name": "Organization Admin",
      "organization_id": "03be5259-f281-478e-a8d0-e7e825e525f2",
      "user_type": "organization",
      "role_type": "custom",
      "description": "This is the organization admin role",
      "created_by": "770e8400-e29b-41d4-a716-446655440222",
      "updated_by": "770e8400-e29b-41d4-a716-446655440222",
      "deleted_by": null,
      "created_at": "2026-05-20T08:30:00.000Z",
      "updated_at": "2026-05-20T08:30:00.000Z"
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	Validation failed (required field empty, organization_id not a UUID, body contains an unknown field)
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Organization admin sent an organization_id belonging to another organization · missing create-role permission

Side effects

• Creates a new row in the roles table and links it to rows in the role_permissions pivot table.
• Emits BusinessEvent RESOURCE_CREATED (impact HIGH) with resourceId = the new role’s id.

---

GET /v1/acl/roles bearer

List roles within the caller’s organization scope (or cross-organization for MORIA). Supports filters by role_type (custom/default) and user_type.

bearer MORIA, ORGANIZATION read-role

Query params — QueryParamsDto

Param	Type	Default	Notes
page	number	1	Page number
limit	number	10	Records per page
organization_id	string (UUID)	optional	Only used when caller is MORIA. For ORGANIZATION, the server always uses the admin’s own org
role_type	enum RoleType	optional	custom or default
user_type	enum UserType	optional	moria, organization, individual

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "roles fetched successfully",
  "data": {
    "limit": 10,
    "count": 24,
    "currentPage": 1,
    "totalPages": 3,
    "roles": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "organization_admin",
        "display_name": "Organization Admin",
        "organization_id": "03be5259-f281-478e-a8d0-e7e825e525f2",
        "user_type": "organization",
        "role_type": "custom",
        "description": "Organization admin role",
        "created_at": "2026-05-20T08:30:00.000Z",
        "updated_at": "2026-05-20T08:30:00.000Z"
      }
    ]
  }
}

Errors

Status	When it occurs
400 Bad Request	Query param invalid (e.g. role_type not a known enum value)
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Caller role is not MORIA/ORGANIZATION or lacks read-role permission

---

GET /v1/acl/roles/:role_id bearer

Detail of one role by ID. role_id is validated as a UUID via ParseUUIDPipe.

bearer MORIA, ORGANIZATION read-role

Path params

Param	Type	Notes
role_id	UUID	Role ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "role fetched successfully",
  "data": {
    "role": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "organization_admin",
      "display_name": "Organization Admin",
      "organization_id": "03be5259-f281-478e-a8d0-e7e825e525f2",
      "user_type": "organization",
      "role_type": "custom",
      "description": "Organization admin role",
      "created_at": "2026-05-20T08:30:00.000Z",
      "updated_at": "2026-05-20T08:30:00.000Z"
    }
  }
}

Errors

Status	When it occurs
400 Bad Request	role_id is not a UUID
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Missing read-role permission
404 Not Found	Role not found

---

PATCH /v1/acl/roles/:role_id bearer

Update the name, description, or reset the permission list of a role. All fields are optional — send only what changes. If permissions is sent, the old permission list is entirely replaced by the new value.

bearer MORIA, ORGANIZATION update-role RESOURCE_UPDATED

Path params

Param	Type	Notes
role_id	UUID	Role ID

Request body — UpdateRoleDto

Field	Type	Notes
name	string	New role name
description	string	New description
permissions	string[]	New permission list (replace, not append)

Example request

{
  "name": "organization_hr",
  "description": "This is the organization human resource role",
  "permissions": [
    "update-role",
    "read-role",
    "invite-individual-user"
  ]
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "role updated successfully",
  "data": {
    "role": { "...": "same shape as GET /:role_id" }
  }
}

Errors

Status	When it occurs
400 Bad Request	Validation failed
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Missing update-role permission
404 Not Found	Role not found

---

DELETE /v1/acl/roles/:role_id bearer

Delete a role. Soft-delete via deleted_at from AuditableEntity; users still assigned to this role must be reassigned manually before deletion.

bearer MORIA, ORGANIZATION delete-role RESOURCE_DELETED

Path params

Param	Type	Notes
role_id	UUID	Role ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "role deleted successfully"
}

Errors

Status	When it occurs
400 Bad Request	role_id is not a UUID
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Missing delete-role permission
404 Not Found	Role not found

---

PATCH /v1/acl/assign-role bearer

Assign a role to a user, or (if unassign_role: true) detach a role from a user. Only organization/MORIA admins may call this. The permission gate accepts either assign-role or unassign-role.

bearer MORIA, ORGANIZATION assign-role, unassign-role RESOURCE_UPDATED

Request body — AssignRoleDto

Field	Type	Required	Notes
user_id	string (UUID)	optional	ID of the user being assigned / unassigned
role_id	string (UUID)	optional	Target role ID (used when assigning)
unassign_role	boolean	optional	true → the service runs unassign (ignoring role_id) · default false (assign)

Example request

{
  "user_id": "770e8400-e29b-41d4-a716-446655440222",
  "role_id": "03be5259-f281-478e-a8d0-e7e825e525f2",
  "unassign_role": false
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "role assigned successfully",
  "data": {
    "role": { "...": "RoleDto shape, now reflecting the new assignment" }
  }
}

Errors

Status	When it occurs
400 Bad Request	Invalid UUID / body contains an unknown field
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Missing assign-role/unassign-role permission
404 Not Found	User or role not found

---

GET /v1/acl/permissions bearer

List every permission available on the platform. Used by FE to build a role builder UI (e.g. a checkbox per permission). Standard pagination.

bearer MORIA, ORGANIZATION read-permission

Query params

Param	Type	Default	Notes
page	number	1	Page number
limit	number	10	Records per page

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "permissions fetched successfully",
  "data": {
    "limit": 10,
    "count": 100,
    "currentPage": 1,
    "totalPages": 10,
    "permissions": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "name": "create-user",
        "display_name": "Create User",
        "description": "Allows creating new users",
        "category_id": "550e8400-e29b-41d4-a716-446655440001",
        "created_at": "2026-05-20T08:30:00.000Z",
        "updated_at": "2026-05-20T08:30:00.000Z"
      }
    ]
  }
}

Errors

Status	When it occurs
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Missing read-permission permission

---

GET /v1/acl/permissions/:permission_id bearer

Detail of one permission by ID. permission_id is validated as a UUID.

bearer MORIA, ORGANIZATION read-permission

Path params

Param	Type	Notes
permission_id	UUID	Permission ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "permission fetched successfully",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "create-user",
    "display_name": "Create User",
    "description": "Allows creating new users",
    "category_id": "550e8400-e29b-41d4-a716-446655440001",
    "created_at": "2026-05-20T08:30:00.000Z",
    "updated_at": "2026-05-20T08:30:00.000Z"
  }
}

Errors

Status	When it occurs
400 Bad Request	permission_id is not a UUID
401 Unauthorized	Invalid Bearer/cookie token
404 Not Found	Permission not found

---

GET /v1/acl/roles/:role_id/permissions bearer

List permissions attached to a role. Used by FE to display a role summary on the detail screen.

bearer MORIA, ORGANIZATION read-permission

Path params

Param	Type	Notes
role_id	UUID	Role ID

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "organization permissions fetched successfully",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "create-user",
      "display_name": "Create User",
      "description": "Allows creating new users",
      "category_id": "550e8400-e29b-41d4-a716-446655440001",
      "created_at": "2026-05-20T08:30:00.000Z",
      "updated_at": "2026-05-20T08:30:00.000Z"
    }
  ]
}

Errors

Status	When it occurs
400 Bad Request	role_id is not a UUID
401 Unauthorized	Invalid Bearer/cookie token
404 Not Found	Role not found

---

DELETE /v1/acl/roles/:role_id/permissions bearer

Detach one or more permissions from a role. The body contains the list of permission names to revoke.

bearer MORIA, ORGANIZATION delete-permission RESOURCE_UPDATED

Path params

Param	Type	Notes
role_id	UUID	Role ID

Request body — RemovePermissionDto

Field	Type	Required	Notes
permissions	string[]	✓	List of permission names to revoke

Example request

{
  "permissions": [
    "update-role",
    "delete-role"
  ]
}

Response — 200 OK

{
  "status": "success",
  "statusCode": 200,
  "message": "permissions removed successfully"
}

Errors

Status	When it occurs
400 Bad Request	role_id is not a UUID · permissions is empty
401 Unauthorized	Invalid Bearer/cookie token
403 Forbidden	Missing delete-permission permission
404 Not Found	Role not found

---

Reference

Enum: RoleType

• custom — role created by an organization/MORIA admin
• default — built-in platform role (e.g. moria_admin, organization_admin) — cannot be deleted

Enum: UserType

• moria · organization · individual

Common permission strings

• create-role, read-role, update-role, delete-role
• assign-role, unassign-role
• read-permission, delete-permission
• invite-individual-user, invite-organization-admin, invite-moria-admin

Standard error envelope

{
  "message": "you can't create role for another organization",
  "statusCode": 403,
  "error": "Forbidden"
}

message can be a string or an array of strings (multi-field validation errors).

Common HTTP codes

• 400 body/query/param validation
• 401 token expired / missing
• 403 role/permission mismatch or cross-organization
• 404 role / permission not found
• 500 internal — show a generic toast