Skip to main content

Roles & Permissions (RBAC)

Curupira lets you model what your users can do with role-based access control (RBAC). You define permissions, group them into roles, optionally bundle roles into role groups, and assign those to users. Each user's effective permissions are then delivered to your application in the access token.

See the Admin API for the full endpoint reference.

The model​

ConceptWhat it is
PermissionA string you define, meaningful to your app — by convention dot-named resource.action (e.g. orders.read, orders.write, invoices.approve). Curupira treats it as an opaque label; your app decides what it grants.
RoleBelongs to one application; grants a set of permissions (e.g. an orders-manager role granting orders.read + orders.write).
Role groupBelongs to one application; bundles roles so you can assign several at once (e.g. a support group containing orders-viewer + tickets-agent).
AssignmentA user is granted roles and/or role groups. Their effective permissions are the union of all permissions from every assigned role (directly and via groups).

:::info This is application RBAC, not admin access These roles govern what your end-users can do in your applications. Access to the Curupira admin dashboard itself is a separate concern. :::

1 · Choose a permission naming convention​

Permissions are free-form strings, so pick a consistent scheme up front — resource.action is a good default:

orders.read      orders.write      orders.delete
invoices.read    invoices.approve
users.invite     billing.manage

Your application enforces them; Curupira just carries them.

2 · Create roles​

Each role lives in an application and grants a permission set.

curl -X POST https://auth.curupira.api.br/api/admin/roles \
  -H 'Content-Type: application/json' -b cookies.txt \
  -d '{
    "application_id": "<your-application-uuid>",
    "name": "orders-manager",
    "description": "Full access to orders",
    "permissions": ["orders.read", "orders.write", "orders.delete"]
  }'
  • permissions is optional; omit it for a role with none (add them later).
  • Updating a role replaces its full permission set (PUT /api/admin/roles/{id} — PUT semantics), so always send the complete list you want; an omitted list clears them.

Or use the dashboard: Roles → Create, pick the application, name the role, and add permissions.

3 · Group roles (optional)​

Role groups make bulk assignment easier. Create a group, then add member roles to it:

# Create the group
curl -X POST https://auth.curupira.api.br/api/admin/role-groups \
  -H 'Content-Type: application/json' -b cookies.txt \
  -d '{"application_id": "<your-application-uuid>", "name": "support", "description": "Support staff"}'

# Add a role to the group
curl -X PUT -b cookies.txt \
  https://auth.curupira.api.br/api/admin/role-groups/{group_id}/roles/{role_id}

Remove a role from a group with DELETE /api/admin/role-groups/{group_id}/roles/{role_id}, and list a group's roles with GET /api/admin/role-groups/{group_id}/roles.

4 · Assign to users​

Assign a role — or a whole role group — to a user:

# Assign a single role
curl -X POST https://auth.curupira.api.br/api/admin/users/{user_id}/roles \
  -H 'Content-Type: application/json' -b cookies.txt \
  -d '{"role_id": "<role-uuid>"}'

# Assign a role group
curl -X POST https://auth.curupira.api.br/api/admin/users/{user_id}/groups \
  -H 'Content-Type: application/json' -b cookies.txt \
  -d '{"group_id": "<group-uuid>"}'

To see what can still be added to a user, use GET /api/admin/users/{id}/available-roles and .../available-role-groups. Remove a role with DELETE /api/admin/users/{user_id}/roles/{role_id}.

In the dashboard this is the Users → (user) → Assign roles / groups view.

5 · Consume permissions in your app​

A user's effective permissions are aggregated into the permissions claim of the access token Curupira issues. Your application reads that claim and authorizes accordingly:

{
  "sub": "…",
  "permissions": ["orders.read", "orders.write", "orders.delete"]
}

Validate the token (signature via JWKS) and check for the permission a given action requires — e.g. require orders.write before allowing an order edit.

Notes​

  • Roles and role groups are per-application and tenant-scoped — you only ever see and manage your own tenant's roles.
  • Permissions are cumulative: a user with multiple roles/groups gets the union of their permissions.
  • Keep roles coarse and composable; prefer adding a role to a user over minting near-duplicate roles.

Next steps​