Roles API

A role is a named bundle of permissions. This API defines those bundles; assigning a role to a person happens on the Users API. Build roles from scratch, from templates, or by cloning one you already trust.

Create a role

Only role_name is required. Pass permissions to grant access up front, set copy_from_role_id to start from an existing role, or set is_template to make the role reusable. To stamp out several at once, use POST /roles/bulk.

curl https://algapsa.com/api/v1/roles \
  -H "X-API-Key: $ALGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "role_name": "Dispatcher",
    "description": "Triages and assigns inbound tickets",
    "permissions": ["perm_ticket_read", "perm_ticket_assign"]
  }'

Templates and cloning

List the starting points with GET /roles/templates, or duplicate an existing role with POST /roles/{id}/clone when you want a near-copy to adjust.

A role's permissions

Read the current grant with GET /roles/{id}/permissions.PUT /roles/{id}/permissions replaces the whole set in one call, so send the complete list you want — anything you omit is dropped. The permission IDs themselves come from the Permissions API.

Endpoints

Every endpoint links through to its full parameters, request and response schemas, and code samples.