Get Role

Retrieve a specific role by its UUID. This endpoint returns detailed information about a single role.

Endpoint

GET /v1/workspaces/{workspaceId}/role/{roleId}

Authentication

Requires Bearer token authentication. See Authentication for details on obtaining an access token.

Authorization: Bearer YOUR_ACCESS_TOKEN

Path Parameters

Parameter	Type	Required	Description
`workspaceId`	string (UUID)	Yes	The ID of your workspace
`roleId`	string (UUID)	Yes	The UUID of the role to retrieve

Response

Success Response

Status Code: 200 OK

Headers:

X-API-Version: v1

Body:

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Sales Manager",
  "description": "Access to sales-related content",
  "customerRoleId": "sales-manager",
  "createdAt": "2025-11-11T10:00:00Z",
  "updatedAt": "2025-11-11T10:00:00Z"
}

Field	Type	Description
`id`	string (UUID)	Sharely's unique identifier for the role
`name`	string	Display name of the role
`description`	string	Description of the role's purpose
`customerRoleId`	string	Your custom identifier for the role
`createdAt`	string (ISO 8601)	When the role was created
`updatedAt`	string (ISO 8601)	When the role was last updated

Examples

Get Role by UUID

Retrieve a specific role:

curl -X GET \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/550e8400-e29b-41d4-a716-446655440001' \
  -H 'x-api-key: sk-sharely-your-api-key'

Response:

{
  "id": "550e8400-e29b-41d4-a716-446655440001",
  "name": "Sales Manager",
  "description": "Access to sales-related content",
  "customerRoleId": "sales-manager",
  "createdAt": "2025-11-11T10:00:00Z",
  "updatedAt": "2025-11-11T10:00:00Z"
}

Get Role Without Customer Role ID

Roles created without a custom identifier:

curl -X GET \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/987fcdeb-51a2-43f7-b8c9-123456789abc' \
  -H 'x-api-key: sk-sharely-your-api-key'

Response:

{
  "id": "987fcdeb-51a2-43f7-b8c9-123456789abc",
  "name": "Basic User",
  "description": null,
  "customerRoleId": null,
  "createdAt": "2025-11-10T14:00:00Z",
  "updatedAt": "2025-11-10T14:00:00Z"
}

Error Responses

401 Unauthorized

Invalid or missing API key:

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

403 Forbidden

Insufficient permissions:

{
  "error": "Forbidden",
  "message": "Insufficient permissions for this workspace"
}

404 Not Found

Role or workspace not found:

{
  "error": "Not Found",
  "message": "Role not found"
}

Common causes:

Invalid or non-existent roleId
Role was deleted
Wrong workspace ID

500 Internal Server Error

Server error during processing:

{
  "error": "Internal Server Error",
  "message": "Failed to retrieve role"
}

Notes

When to Use This Endpoint

Use this endpoint when:

You have the role's UUID and need to retrieve its details
You want to verify a role's current properties
You're auditing or displaying role information

If you have the customerRoleId instead of the UUID, use the Get by Customer Role ID endpoint.

UUID vs Customer Role ID

This endpoint requires Sharely's internal UUID (roleId). If you only have your custom customerRoleId, you have two options:

Use Get by Customer Role ID - Direct lookup by your custom ID
Use Find Roles - Search with criteria

Related Endpoints

List Roles - Get all roles in workspace
Get by Customer Role ID - Get role by custom identifier
Find Roles - Search for roles by criteria
Update Role - Modify role properties

Use Cases

Display Role Details

Show role information in your application:

async function displayRole(workspaceId, roleId) {
  const response = await fetch(
    `https://api.sharely.ai/v1/workspaces/${workspaceId}/role/${roleId}`,
    {
      headers: { 'x-api-key': 'sk-sharely-your-api-key' }
    }
  );
 
  const role = await response.json();
  console.log(`Role: ${role.name}`);
  console.log(`Description: ${role.description}`);
  console.log(`Customer ID: ${role.customerRoleId}`);
}

Verify Role Exists

Check if a role exists before performing operations:

async function verifyRole(workspaceId, roleId) {
  try {
    const response = await fetch(
      `https://api.sharely.ai/v1/workspaces/${workspaceId}/role/${roleId}`,
      {
        headers: { 'x-api-key': 'sk-sharely-your-api-key' }
      }
    );
 
    if (response.ok) {
      return true;
    }
    return false;
  } catch (error) {
    return false;
  }
}