Roles

Roles carry a JSONB permissions array. Users can be assigned zero-or-more roles; permission checks are performed in /client/roles/check/:permission against the union of the user's role permission lists.

Endpoints

Method	Path	Description
POST	`/admin/projects/:projectId/roles`	Create a role.
GET	`/admin/projects/:projectId/roles`	List roles.
PATCH	`/admin/projects/:projectId/roles/:roleId`	Partial update.
DELETE	`/admin/projects/:projectId/roles/:roleId`	Delete a role.
POST	`/admin/projects/:projectId/roles/assign`	Assign a role to a user.
POST	`/admin/projects/:projectId/roles/revoke`	Revoke a role from a user.
GET	`/admin/projects/:projectId/roles/:roleId/users`	List users with a given role.

POST /admin/projects/:projectId/roles

Request (`CreateRoleInput`)

Field	Type	Required
`name`	string	yes
`description`	string	no
`permissions`	string[]	yes

Response 201

{
  "data": {
    "id": "…",
    "name": "moderator",
    "permissions": ["reviews.moderate", "moderation.approve"]
  }
}

Try it:

POST/admin/projects/%7B%7BprojectId%7D%7D/roles

developer auth

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/roles' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "moderator",
  "permissions": [
    "posts.delete"
  ]
}'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST "${BASE_URL}/admin/projects/${PROJECT_ID}/roles" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"name":"moderator","permissions":["posts.delete"]}'

GET /admin/projects/:projectId/roles

{ "data": [{ "id": "…", "name": "moderator", "permissions": ["…"] }] }

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/roles

developer auth

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/roles'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET "${BASE_URL}/admin/projects/${PROJECT_ID}/roles" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

PATCH /admin/projects/:projectId/roles/:roleId

Allowed fields: name, description, permissions.

Try it:

PATCH/admin/projects/%7B%7BprojectId%7D%7D/roles/%7B%7BroleId%7D%7D

developer auth

curl -X PATCH 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/roles/%7B%7BroleId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X PATCH "${BASE_URL}/admin/projects/${PROJECT_ID}/roles/{roleId}" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{}'

DELETE /admin/projects/:projectId/roles/:roleId

{ "data": { "deleted": true } }

Try it:

DELETE/admin/projects/%7B%7BprojectId%7D%7D/roles/%7B%7BroleId%7D%7D

developer auth

curl -X DELETE 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/roles/%7B%7BroleId%7D%7D'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X DELETE "${BASE_URL}/admin/projects/${PROJECT_ID}/roles/{roleId}" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

POST /admin/projects/:projectId/roles/assign

Request (`AssignRoleInput`)

Field	Type	Required
`app_user_id`	uuid	yes
`role_id`	uuid	yes

Response 201

{ "data": { "app_user_id": "…", "role_id": "…", "assigned_by": "admin", "assigned_at": "…" } }

Try it:

POST/admin/projects/%7B%7BprojectId%7D%7D/roles/assign

developer auth

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/roles/assign' \
  -H 'Content-Type: application/json' \
  -d '{
  "app_user_id": "<app_user_id>",
  "role_id": "<role_id>"
}'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST "${BASE_URL}/admin/projects/${PROJECT_ID}/roles/assign" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"app_user_id":"<app_user_id>","role_id":"<role_id>"}'

POST /admin/projects/:projectId/roles/revoke

Same request shape as /assign. Deletes the user_roles row.

Response 200

{ "data": { "revoked": true } }

Try it:

POST/admin/projects/%7B%7BprojectId%7D%7D/roles/revoke

developer auth

curl -X POST 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/roles/revoke' \
  -H 'Content-Type: application/json' \
  -d '{
  "app_user_id": "<app_user_id>",
  "role_id": "<role_id>"
}'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X POST "${BASE_URL}/admin/projects/${PROJECT_ID}/roles/revoke" \
  -H "Authorization: Bearer ${DEV_TOKEN}" \
  -H 'Content-Type: application/json' \
  -d '{"app_user_id":"<app_user_id>","role_id":"<role_id>"}'

GET /admin/projects/:projectId/roles/:roleId/users

{
  "data": [
    {
      "app_user_id": "…",
      "role_id": "…",
      "app_users": { "id": "…", "display_name": "…", "email": "…" }
    }
  ]
}

Try it:

GET/admin/projects/%7B%7BprojectId%7D%7D/roles/%7B%7BroleId%7D%7D/users

developer auth

curl -X GET 'https://api.amba.dev/v1/admin/projects/%7B%7BprojectId%7D%7D/roles/%7B%7BroleId%7D%7D/users'

Loading auth… Configure auth in the settings drawer (top-right) to run this request.

Curl:

curl -X GET "${BASE_URL}/admin/projects/${PROJECT_ID}/roles/{roleId}/users" \
  -H "Authorization: Bearer ${DEV_TOKEN}"

On this page