How Do I Interact with Roles via API?

Version Number: v1.0.0

Published Date: 25 May 2026

____________________________________________________________________________

What are these Entities?

• Roles: Named “bundles” of access rules (for example: Auditor, Admin, Read-only).

• Role permissions: The actual “what a role can do” entries inside a role (what resource/action/value is allowed, plus how broadly it applies).

• User role assignments: The link between a user and a role (assign/unassign users to roles).

Below are the available endpoints User APIs.

Permission names (the key ones you’ll see)

• assign_role: Allows assigning/unassigning roles to users.

• plus the action permission on the role: create, edit, or delete

• For editing role permissions, the permission you need is effectively “edit this role”:

• User API: requires edit on the role

• For viewing a specific role-permission entry (User API show), it requires view on the role.

For more info, please check out the User Permissions Map

User APIs (/api/v1)

Roles

All paths are under: /api/v1/roles...

• GET /api/v1/roles.json

  • What it does: Lists roles visible to the signed-in user.

  • Permissions needed: Role visibility.

• GET /api/v1/roles/:id.json

  • What it does: Returns one role.

  • Permissions needed: Role visibility.

• POST /api/v1/roles.json

  • What it does: Creates an organization-scoped role (user API does not create global roles).

  • Permissions needed: create on roles for the target owning organization.

• PUT /api/v1/roles/:id.json

  • What it does: Updates role name/description.

  • Permissions needed: edit on the role (and create on roles for its owner org).

• DELETE /api/v1/roles/:id.json

  • What it does: Deletes a role (only if not assigned to users).

  • Permissions needed: delete on the role.

Role permissions (inside a role)

All paths are under: /api/v1/roles/:role_id/role_permissions...

• GET /api/v1/roles/:role_id/role_permissions.json

  • What it does: Lists role permission entries.

  • Permissions needed: Must be allowed to view the role.

• GET /api/v1/roles/:role_id/role_permissions/:id.json

  • What it does: Returns one role permission entry.

  • Permissions needed: view on the role.

• POST /api/v1/roles/:role_id/role_permissions.json

  • What it does: Adds a permission entry.

  • Permissions needed: edit on the role.

• PUT /api/v1/roles/:role_id/role_permissions/:id.json

  • What it does: Updates a permission entry.

  • Permissions needed: edit on the role.

• DELETE /api/v1/roles/:role_id/role_permissions/:id.json

  • What it does: Removes a permission entry.

  • Permissions needed: edit on the role.

• PUT /api/v1/roles/:role_id/role_permissions/bulk_update.json

  • What it does: Bulk create/update permission entries.

  • Permissions needed: edit on the role.

• POST /api/v1/roles/:role_id/role_permissions/bulk_delete.json

  • What it does: Bulk delete by ids.

  • Permissions needed: edit on the role.

Role permission payload difference (User API)

• User roles can use scope_strategy only from: user_org, resource, role_owner (no global).

User role assignments

All paths are under: /api/v1/users/:user_id/role_assignments...

• GET /api/v1/users/:user_id/role_assignments.json

  • What it does: Lists roles assigned to the user.

  • Permissions needed: Must be allowed to view that user.

• POST /api/v1/users/:user_id/role_assignments.json

  • What it does: Assign a role (pass role_id).

  • Permissions needed: assign_role on the target user.

• POST /api/v1/users/:user_id/role_assignments/unassign_role.json

  • What it does: Unassign a role (pass role_id).

  • Permissions needed: assign_role on the target user.

• DELETE /api/v1/users/:user_id/role_assignments/:id.json

  • What it does: Removes one role assignment record.

  • Permissions needed: assign_role on the target user.