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/:roleId

Authentication: 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

1{2  "success": true,3  "message": "Role fetched successfully",4  "data": {5    "_id": "66b0...c9d0",6    "name": "Sales Manager",7    "slug": "sales-manager",8    "description": "Manages the sales desk",9    "permissions": [10      "chat.read",11      "chat.assign"12    ],13    "isDefault": false,14    "isSystem": false,15    "metadata": {16      "color": "#3b82f6"17    },18    "createdAt": "2026-06-23T10:00:00.000Z",19    "updatedAt": "2026-06-23T10:00:00.000Z"20  },21  "error": null22}

Common Errors

Get fails when the token is invalid or the role id does not exist.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

HTTP 403 Forbidden - Tenant admin required

json

1{2  "success": false,3  "message": "Access denied: tenant admin privileges required",4  "data": null,5  "error": null6}

HTTP 404 Not Found - Role missing

json

1{2  "success": false,3  "message": "Entity not found",4  "data": null,5  "error": "Entity not found"6}

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 roleId is a 24-character ObjectId before calling Get.
If isSystem is 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.

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.

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

Tenant (client) id. Required when is-tenant=true.

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

1{2  "success": true,3  "message": "Role fetched successfully",4  "data": {5    "_id": "66b0...c9d0",6    "name": "Sales Manager",7    "slug": "sales-manager",8    "description": "Manages the sales desk",9    "permissions": [10      "chat.read",11      "chat.assign"12    ],13    "isDefault": false,14    "isSystem": false,15    "metadata": {16      "color": "#3b82f6"17    },18    "createdAt": "2026-06-23T10:00:00.000Z",19    "updatedAt": "2026-06-23T10:00:00.000Z"20  },21  "error": null22}

Common Errors

Get fails when the token is invalid or the role id does not exist.

HTTP 401 Unauthorized - No token

json

1{2  "success": false,3  "message": "No token, authorization denied",4  "data": null,5  "error": "Unauthorized"6}

HTTP 403 Forbidden - Tenant admin required

json

1{2  "success": false,3  "message": "Access denied: tenant admin privileges required",4  "data": null,5  "error": null6}

HTTP 404 Not Found - Role missing

json

1{2  "success": false,3  "message": "Entity not found",4  "data": null,5  "error": "Entity not found"6}

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.