API Reference
Get Custom Role
Overview
Fetch a single role by its roleId for the client Platform Custom Roles detail or edit screen.
Returns name, slug, description, permissions, system/default flags, and metadata so you can hydrate an edit form before calling Update.
When to use this endpoint?
Use Get Custom Role when:
- Opening a role detail drawer from Platform → Custom Roles.
- Loading the latest permissions before an Update request.
- Confirming a role still exists before Delete.
- Showing whether the role is system-managed (
isSystem) so the UI can lock edits.
Part of the client Platform Custom Roles module. Get roleId from List Custom Roles.
Response Data
The data object typically includes:
| Field | Description |
|---|---|
| _id | Role id (same as path roleId). |
| name | Display name. |
| slug | Stable slug used when assigning users. Not changed by Update. |
| description | Role summary text. |
| permissions | Array of permission keys granted by this role. |
| isSystem / isDefault | Built-in role flags. Treat system roles as read-only in the UI when your product policy requires it. |
| metadata | Optional attributes such as badge color. |
GET
{baseUrl}/api/{apiVersion}/user-role/:roleIdAuthentication
Required (Bearer token)
Tenant-scoped
Yes (tenant DB — requires x-client-id)
Request Headers
| Header | Value | Description |
|---|---|---|
| Authorization | Bearer <access_token> | Client Access Token with tenant admin privileges (Platform panel). |
| is-tenant | true | Targets the tenant DB ("true", needs x-client-id). |
| x-client-id | {{clientId}} | Tenant (client) id. Required when is-tenant=true. |
Path Parameters
| Parameter | Example | Description |
|---|---|---|
| roleId | 66b0f1a2c3d4e5f6a7b8c9d0 | The role's _id (24-char Mongo ObjectId). Get it from List Custom Roles. |
Success Response (HTTP 200 OK)
On success, the API returns the full role document.
json
{
"success": true,
"message": "Role fetched successfully",
"data": {
"_id": "66b0...c9d0",
"name": "Sales Manager",
"slug": "sales-manager",
"description": "Manages the sales desk",
"permissions": [
"chat.read",
"chat.assign"
],
"isDefault": false,
"isSystem": false,
"metadata": {
"color": "#3b82f6"
},
"createdAt": "2026-06-23T10:00:00.000Z",
"updatedAt": "2026-06-23T10:00:00.000Z"
},
"error": null
}Common Errors
Get fails when the token is invalid or the role id does not exist.
HTTP 401 Unauthorized — No token
json
{
"success": false,
"message": "No token, authorization denied",
"data": null,
"error": "Unauthorized"
}HTTP 403 Forbidden — Tenant admin required
json
{
"success": false,
"message": "Access denied: tenant admin privileges required",
"data": null,
"error": null
}HTTP 404 Not Found — Role missing
json
{
"success": false,
"message": "Entity not found",
"data": null,
"error": "Entity not found"
}| Code | Reason |
|---|---|
| 401 Unauthorized | Access Token is missing, invalid, or expired. |
| 403 Forbidden | Tenant admin privileges required for Platform Custom Roles. |
| 404 Not Found | No role exists for the given roleId. |
| 500 Internal Server Error | An unexpected error occurred while fetching the role. |
Best Practices
- Validate
roleIdis a 24-character ObjectId before calling Get. - If
isSystemis true, disable delete (and optionally edit) in the Platform UI. - Prefer List for tables; use Get when opening a single role editor.
- Always send tenant headers with a client Bearer token over HTTPS.
Role details ready
Bind fields to your edit form, then call Update to save changes or Delete if the role is custom and unused.