Skip to main content

Roles

6 API calls in this section.

List Roles​

Platform & Access / Roles
GET/roles?language=en&scope=&search=&page=1&limit=10

Retrieves a paginated list of roles with optional filtering by scope Authentication: - Requires valid authentication token Query Parameters: - language (optional): Language code for localized response messages (e.g., 'en') - scope (optional): Filter roles by scope ('system' or 'tenant') - page (optional): Page number for pagination (default: 1) - limit (optional): Number of records per page (default: 10)

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request GET "$ONDI_BASE_URL/roles?language=en&scope=&search=&page=1&limit=10" \2  --header "Authorization: Bearer {{access_token}}"

Query parameters

languageOptional
query string

en

Language code for response localization (Optional, default: en)

scopeOptional
query string

Filter roles by scope (Optional, values: 'system', 'tenant')

searchOptional
query string

Search roles by name or description (Optional)

pageOptional
query string

1

Page number for pagination (Optional, default: 1)

limitOptional
query string

10

Number of records per page (Optional, default: 10)

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Responses

Success Response200OK
Response body
json
1{2  "success": true,3  "message": "Roles retrieved successfully",4  "roles": [5    {6      "id": "role-001",7      "name": "System Admin",8      "description": "System administrator with full access",9      "scope": "system",10      "created_at": "2023-01-01T00:00:00Z",11      "updated_at": "2023-01-01T00:00:00Z"12    },13    {14      "id": "role-002",15      "name": "System Auditor",16      "description": "Read-only access to system resources",17      "scope": "system",18      "created_at": "2023-01-01T00:00:00Z",19      "updated_at": "2023-01-01T00:00:00Z"20    }21  ],22  "total": 2,23  "page": 1,24  "limit": 1025}
Error Response500Internal Server Error
Response body
json
1{2  "success": false,3  "message": "Error retrieving roles"4}
Success (200 OK)200
Response body
json
1{2  "success": true,3  "message": "Roles retrieved successfully",4  "roles": [5    {6      "id": "role-uuid",7      "name": "Admin",8      "description": "System administrator with full access",9      "scope": "system",10      "created_at": "2023-01-01T00:00:00Z",11      "updated_at": "2023-01-01T00:00:00Z"12    }13  ],14  "total": 5,15  "page": 1,16  "limit": 1017}

Create Role​

Platform & Access / Roles
POST/roles?language=en

Creates a new role with the specified name, description, and scope. Authentication: - Requires valid authentication token - User must have appropriate permissions to create roles Query Parameters: - language (optional): Language code for localized response messages (e.g., 'en') Required Fields: - name: Role name (must be unique within its scope) - description: Role description - scope: Role scope ('system' or 'tenant')

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request POST "$ONDI_BASE_URL/roles?language=en" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --header "Content-Type: application/json" \5  --data '{6  "name": "example_role",7  "description": "Example role description",8  "scope": "tenant"9}'
Request body
json
1{2  "name": "example_role",3  "description": "Example role description",4  "scope": "tenant"5}

Query parameters

languageOptional
query string

en

Language code for response localization (Optional, default: en)

Request body fields

nameExample
string

Example field from the request body.

descriptionExample
string

Example field from the request body.

scopeExample
string

Example field from the request body.

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Content-TypeOptional
header string

application/json

Responses

Success Response201
Response body
json
1{2  "success": true,3  "message": "Role created successfully",4  "role": {5    "id": "new-role-uuid",6    "name": "example_role",7    "description": "Example role description",8    "scope": "tenant",9    "created_at": "2023-01-01T00:00:00Z",10    "updated_at": "2023-01-01T00:00:00Z"11  }12}
Error - Bad Request400
Response body
json
1{2  "success": false,3  "message": "Invalid input data"4}
Error - Conflict409
Response body
json
1{2  "success": false,3  "message": "Role with this name already exists"4}

Update Role​

Platform & Access / Roles
PUT/roles/:roleId?language=en

Updates an existing role's name and/or description. Authentication: - Requires valid authentication token - User must have appropriate permissions to update roles Path Parameters: - roleId: UUID of the role to update (Required) Query Parameters: - language (optional): Language code for localized response messages (e.g., 'en') Updatable Fields: - name: New role name (must be unique within its scope) - description: New role description Note: Only provided fields will be updated. Fields not included in the request will remain unchanged.

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request PUT "$ONDI_BASE_URL/roles/:roleId?language=en" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --header "Content-Type: application/json" \5  --data '{6  "name": "updated_role_name",7  "description": "Updated role description"8}'
Request body
json
1{2  "name": "updated_role_name",3  "description": "Updated role description"4}

Path parameters

roleIdRequired
path string

role-uuid

UUID of the role to update (Required)

Query parameters

languageOptional
query string

en

Language code for response localization (Optional, default: en)

Request body fields

nameExample
string

Example field from the request body.

descriptionExample
string

Example field from the request body.

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Content-TypeOptional
header string

application/json

Responses

Success Response200
Response body
json
1{2  "success": true,3  "message": "Role updated successfully",4  "role": {5    "id": "role-uuid",6    "name": "updated_role_name",7    "description": "Updated role description",8    "scope": "system",9    "created_at": "2023-01-01T00:00:00Z",10    "updated_at": "2023-01-01T00:00:00Z"11  }12}
Error - Not Found404
Response body
json
1{2  "success": false,3  "message": "Role not found"4}
Error - Conflict409
Response body
json
1{2  "success": false,3  "message": "Role with this name already exists"4}

Delete Role​

Platform & Access / Roles
DELETE/roles/:roleId?language=en

Deletes a role by its ID. System roles and roles with active user assignments cannot be deleted. Authentication: - Requires valid authentication token - User must have appropriate permissions to delete roles Path Parameters: - roleId: UUID of the role to delete (Required) Query Parameters: - language (optional): Language code for localized response messages (e.g., 'en') Business Rules: - System roles cannot be deleted - Roles with active user assignments cannot be deleted

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request DELETE "$ONDI_BASE_URL/roles/:roleId?language=en" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

roleIdRequired
path string

role-uuid

UUID of the role to delete (Required)

Query parameters

languageOptional
query string

en

Language code for response localization (Optional, default: en)

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Responses

Success Response200
Response body
json
1{2  "success": true,3  "message": "Role deleted successfully"4}
Error - Not Found404
Response body
json
1{2  "success": false,3  "message": "Role not found"4}
Error - Cannot Delete System Role400
Response body
json
1{2  "success": false,3  "message": "Cannot delete system role"4}
Error - Role Has Users409
Response body
json
1{2  "success": false,3  "message": "Cannot delete role with active user assignments"4}

Assign Permission to Role​

Platform & Access / Roles
POST/roles/:roleId/permissions?language=en

Assigns a permission to a role. The permission scope must match the role scope. Authentication: - Requires valid authentication token - User must have appropriate permissions to manage roles Path Parameters: - roleId: UUID of the role to assign the permission to (Required) Query Parameters: - language (optional): Language code for localized response messages (e.g., 'en') Required Fields: - permission_id: UUID of the permission to assign to the role Business Rules: - Permission scope must match role scope (system permissions can only be assigned to system roles, tenant permissions to tenant roles) - Cannot assign a permission that is already assigned to the role

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request POST "$ONDI_BASE_URL/roles/:roleId/permissions?language=en" \2  --header "Authorization: Bearer {{access_token}}" \3  --header "Content-Type: application/json" \4  --header "Content-Type: application/json" \5  --data '{6  "permission_ids": [7    "permission-uuid1",8    "permission-uuid2"9  ]10}'
Request body
json
1{2  "permission_ids": [3    "permission-uuid1",4    "permission-uuid2"5  ]6}

Path parameters

roleIdRequired
path string

role-uuid

UUID of the role to assign the permission to (Required)

Query parameters

languageOptional
query string

en

Language code for response localization (Optional, default: en)

Request body fields

permission_idsExample
array<string>

Example field from the request body.

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Content-TypeOptional
header string

application/json

Responses

Success Response201
Response body
json
1{2  "success": true,3  "message": "Permission assigned successfully"4}
Error - Not Found404
Response body
json
1{2  "success": false,3  "message": "Role or permission not found"4}
Error - Scope Mismatch400
Response body
json
1{2  "success": false,3  "message": "Permission scope does not match role scope"4}
Error - Already Assigned409
Response body
json
1{2  "success": false,3  "message": "Permission already assigned to role"4}

Remove Permission from Role​

Platform & Access / Roles
DELETE/roles/:roleId/permissions/:permissionId?language=en

Removes a permission from a role. Authentication: - Requires valid authentication token - User must have appropriate permissions to manage roles Path Parameters: - roleId: UUID of the role to remove the permission from (Required) - permissionId: UUID of the permission to remove (Required) Query Parameters: - language (optional): Language code for localized response messages (e.g., 'en') Business Rules: - Cannot remove a permission that is not assigned to the role - Some system-critical permission-role combinations may be protected from removal

Send a bearer token in the Authorization header for an authenticated OnDi user session.
Request
curl
1curl --request DELETE "$ONDI_BASE_URL/roles/:roleId/permissions/:permissionId?language=en" \2  --header "Authorization: Bearer {{access_token}}"

Path parameters

roleIdRequired
path string

role-uuid

UUID of the role to remove the permission from (Required)

permissionIdRequired
path string

permission-uuid

UUID of the permission to remove (Required)

Query parameters

languageOptional
query string

en

Language code for response localization (Optional, default: en)

Headers

AuthorizationOptional
header string

Bearer {{access_token}}

Responses

Success Response200
Response body
json
1{2  "success": true,3  "message": "Permission removed successfully"4}
Error - Not Found404
Response body
json
1{2  "success": false,3  "message": "Role or permission not found"4}
Error - Not Assigned400
Response body
json
1{2  "success": false,3  "message": "Permission is not assigned to this role"4}
Error - System Critical403
Response body
json
1{2  "success": false,3  "message": "Cannot remove system-critical permission"4}