Get by Customer Role ID

Retrieve a role using your customer-provided role identifier. This endpoint provides a convenient way to look up roles using your own naming conventions instead of Sharely's internal UUIDs.

Endpoint

GET /v1/workspaces/{workspaceId}/role/by-customer-role-id/{customerRoleId}

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
`customerRoleId`	string	Yes	Your custom role identifier (e.g., "sales-manager")

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

Basic Lookup

Retrieve a role by your custom identifier:

curl -X GET \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/by-customer-role-id/sales-manager' \
  -H 'x-api-key: sk-sharely-your-api-key'

Response:

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Sales Manager",
  "description": "Access to sales content",
  "customerRoleId": "sales-manager",
  "createdAt": "2025-11-11T10:00:00Z",
  "updatedAt": "2025-11-11T10:00:00Z"
}

URL Encoding

For customer role IDs with special characters, ensure proper URL encoding:

# Customer role ID: "sales/manager"
curl -X GET \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/by-customer-role-id/sales%2Fmanager' \
  -H 'x-api-key: sk-sharely-your-api-key'

Get UUID for Further Operations

Retrieve the Sharely UUID for use in other API calls:

# Get role details
ROLE_DATA=$(curl -X GET \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/by-customer-role-id/sales-manager' \
  -H 'x-api-key: sk-sharely-your-api-key')
 
# Extract UUID
ROLE_ID=$(echo $ROLE_DATA | jq -r '.id')
 
# Use UUID in another call
curl -X PUT \
  "https://api.sharely.ai/v1/workspaces/your-workspace-id/role/${ROLE_ID}" \
  -H 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Senior Sales Manager"}'

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 with the specified customer role ID not found:

{
  "error": "Not Found",
  "message": "Role with customerRoleId 'sales-manager' not found"
}

Common causes:

Customer role ID doesn't exist
Typo in customer role ID
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 your custom customerRoleId and need the full role details
You want to verify a role exists by your identifier
You need to get Sharely's UUID for subsequent operations
You're integrating with external systems using your identifiers

vs Find Endpoint

The Find Roles endpoint also supports searching by customer role ID, but this endpoint:

Is simpler for exact matches
Returns a single role object (not an array)
Has a cleaner URL structure
Returns 404 if not found (vs empty array)

Use this endpoint for direct lookups, use Find for searching.

Case Sensitivity

Customer role IDs are case-sensitive. "sales-manager" and "Sales-Manager" are different identifiers.

URL Encoding

Always URL-encode the customerRoleId in the path:

Spaces: my%20role
Slashes: sales%2Fmanager
Special characters: encode appropriately

Related Endpoints

Get Role - Get role by Sharely UUID
Find Roles - Search with flexible criteria
List Roles - Get all roles
Upsert Role - Create or update by customer role ID

Use Cases

Map External Roles

Map roles from your identity provider to Sharely roles:

async function getSharelyRole(workspaceId, externalRoleId) {
  try {
    const response = await fetch(
      `https://api.sharely.ai/v1/workspaces/${workspaceId}/role/by-customer-role-id/${externalRoleId}`,
      {
        headers: { 'x-api-key': 'sk-sharely-your-api-key' }
      }
    );
 
    if (response.ok) {
      return await response.json();
    }
    return null;
  } catch (error) {
    console.error('Failed to get role:', error);
    return null;
  }
}

Generate Role-Bound Tokens

Get role details before generating tokens:

async function generateTokenForUser(workspaceId, userId, customerRoleId) {
  // Get role details
  const role = await fetch(
    `https://api.sharely.ai/v1/workspaces/${workspaceId}/role/by-customer-role-id/${customerRoleId}`,
    {
      headers: { 'x-api-key': 'sk-sharely-your-api-key' }
    }
  ).then(r => r.json());
 
  // Generate token with role
  const tokenResponse = await fetch(
    `https://api.sharely.ai/v1/workspaces/${workspaceId}/activate-or-retrieve-user-space`,
    {
      method: 'PUT',
      headers: {
        'x-api-key': 'sk-sharely-your-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        userId,
        roleId: role.id
      })
    }
  );
 
  return await tokenResponse.json();
}

Verify Role Exists

Check if a role exists before creating:

async function ensureRole(workspaceId, customerRoleId, roleData) {
  // Check if exists
  const response = await fetch(
    `https://api.sharely.ai/v1/workspaces/${workspaceId}/role/by-customer-role-id/${customerRoleId}`,
    {
      headers: { 'x-api-key': 'sk-sharely-your-api-key' }
    }
  );
 
  if (response.ok) {
    console.log('Role already exists');
    return await response.json();
  }
 
  // Create if doesn't exist
  const createResponse = await fetch(
    `https://api.sharely.ai/v1/workspaces/${workspaceId}/role`,
    {
      method: 'POST',
      headers: {
        'x-api-key': 'sk-sharely-your-api-key',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        customerRoleId,
        ...roleData
      })
    }
  );
 
  return await createResponse.json();
}

Lookup Table

Build a lookup table for quick access:

async function buildRoleLookup(workspaceId, customerRoleIds) {
  const lookup = {};
 
  for (const customerRoleId of customerRoleIds) {
    try {
      const response = await fetch(
        `https://api.sharely.ai/v1/workspaces/${workspaceId}/role/by-customer-role-id/${customerRoleId}`,
        {
          headers: { 'x-api-key': 'sk-sharely-your-api-key' }
        }
      );
 
      if (response.ok) {
        const role = await response.json();
        lookup[customerRoleId] = role.id;
      }
    } catch (error) {
      console.error(`Failed to lookup role ${customerRoleId}:`, error);
    }
  }
 
  return lookup;
}
 
// Usage
const roleLookup = await buildRoleLookup(workspaceId, [
  'admin',
  'editor',
  'viewer'
]);
// { admin: 'uuid-1', editor: 'uuid-2', viewer: 'uuid-3' }