Skip to main content

​
Overview

The Roles API provides endpoints for managing roles within the system. Roles are used to group permissions and assign them to users.

​
List Roles

Retrieve all roles available for the current tenant. 
curl -X GET https://api.example.com/api/v1/identity/roles \
  -H "Authorization: Bearer {access_token}"

​
HTTP Request

GET /api/v1/identity/roles

​
Authorization

Requires Permissions.Roles.View permission.

​
Response

Returns an array of RoleDto objects.
​
id
string
Role’s unique identifier
​
name
string
Role name
​
description
string
Role description (optional)
​
permissions
array<string>
Array of permission strings assigned to the role (optional)

​
Response Example

[
  {
    "id": "admin-role-id",
    "name": "Administrator",
    "description": "Full system access",
    "permissions": [
      "Permissions.Users.View",
      "Permissions.Users.Create",
      "Permissions.Users.Update",
      "Permissions.Users.Delete"
    ]
  },
  {
    "id": "user-role-id",
    "name": "User",
    "description": "Basic user access",
    "permissions": [
      "Permissions.Users.View"
    ]
  }
]

​
Get Role by ID

Retrieve a specific role by its unique identifier. 
curl -X GET https://api.example.com/api/v1/identity/roles/{roleId} \
  -H "Authorization: Bearer {access_token}"

​
HTTP Request

GET /api/v1/identity/roles/{id}

​
Authorization

Requires Permissions.Roles.View permission.

​
Path Parameters

​
id
guid
required
The unique identifier of the role

​
Response

Returns a RoleDto object with role details.

​
Create or Update Role

Create a new role or update an existing role’s name and description. 
curl -X POST https://api.example.com/api/v1/identity/roles \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "custom-role-id",
    "name": "Manager",
    "description": "Department manager role"
  }'

​
HTTP Request

POST /api/v1/identity/roles

​
Authorization

Requires Permissions.Roles.Create permission.

​
Request Body

​
id
string
required
Role ID. If the role exists, it will be updated; otherwise, a new role is created.
​
name
string
required
Role name (must be unique within the tenant)
​
description
string
Role description (optional)

​
Response

Returns the created or updated RoleDto object.

​
Response Example

{
  "id": "custom-role-id",
  "name": "Manager",
  "description": "Department manager role",
  "permissions": []
}

​
Update Role Permissions

Replace the set of permissions assigned to a role. 
curl -X PUT https://api.example.com/api/v1/identity/{roleId}/permissions \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "roleId": "custom-role-id",
    "permissions": [
      "Permissions.Users.View",
      "Permissions.Users.Create",
      "Permissions.Products.View"
    ]
  }'

​
HTTP Request

PUT /api/v1/identity/{id}/permissions

​
Authorization

Requires Permissions.Roles.Update permission.

​
Path Parameters

​
id
string
required
The unique identifier of the role

​
Request Body

​
roleId
string
required
The ID of the role to update (must match the path parameter)
​
permissions
array<string>
required
Array of permission strings to assign to the role. This replaces all existing permissions.

​
Response

Returns a success message string.

​
Response Example

"Permissions updated successfully"

​
Error Responses

​
400
error
Bad Request - Role ID in path doesn’t match request body

​
Get Role with Permissions

Retrieve a role along with its assigned permissions. 
curl -X GET https://api.example.com/api/v1/identity/roles/{roleId}/permissions \
  -H "Authorization: Bearer {access_token}"

​
HTTP Request

GET /api/v1/identity/roles/{id}/permissions

​
Authorization

Requires Permissions.Roles.View permission.

​
Path Parameters

​
id
string
required
The unique identifier of the role

​
Response

Returns a RoleDto object including the permissions array.

​
Delete Role

Remove an existing role by its unique identifier. 
curl -X DELETE https://api.example.com/api/v1/identity/roles/{roleId} \
  -H "Authorization: Bearer {access_token}"

​
HTTP Request

DELETE /api/v1/identity/roles/{id}

​
Authorization

Requires Permissions.Roles.Delete permission.

​
Path Parameters

​
id
guid
required
The unique identifier of the role to delete

​
Response

Returns 204 No Content on successful deletion.

​
Notes

  • System roles cannot be deleted
  • Roles assigned to users may require reassignment before deletion
  • Deleting a role removes all permission assignments for that role

Build docs developers (and LLMs) love

Get started for freeTalk to us