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

This endpoint requires a Bearer token obtained through the two-step authentication flow:

  1. First, generate an access token using your API key
  2. Use that access token in the Authorization header

See Authentication for the complete authentication flow.

Headers

HeaderTypeRequiredDescription
AuthorizationstringYesBearer token with access token
organizationidstring (UUID)YesYour organization ID

Path Parameters

ParameterTypeRequiredDescription
workspaceIdstring (UUID)YesThe ID of your workspace
customerRoleIdstringYesYour 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"
}
FieldTypeDescription
idstring (UUID)Sharely's unique identifier for the role
namestringDisplay name of the role
descriptionstringDescription of the role's purpose
customerRoleIdstringYour custom identifier for the role
createdAtstring (ISO 8601)When the role was created
updatedAtstring (ISO 8601)When the role was last updated

Examples

Basic Lookup

Retrieve a role by your custom identifier:

# Step 1: Generate access token (do this once, reuse for multiple requests)
ACCESS_TOKEN=$(curl -s -X POST \
  'https://api.sharely.ai/workspaces/your-workspace-id/generate-access-key-token' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: sk-sharely-your-api-key' \
  -d '{}' | jq -r '.token')
 
# Step 2: Get role using the access token
curl -X GET \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/by-customer-role-id/sales-manager' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'organizationid: your-organization-id'

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"
# Using the access token from Step 1 above
curl -X GET \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/by-customer-role-id/sales%2Fmanager' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'organizationid: your-organization-id'

Get UUID for Further Operations

Retrieve the Sharely UUID for use in other API calls:

# Using the access token from Step 1 above
 
# Get role details
ROLE_DATA=$(curl -s -X GET \
  'https://api.sharely.ai/v1/workspaces/your-workspace-id/role/by-customer-role-id/sales-manager' \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H 'organizationid: your-organization-id')
 
# 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 $ACCESS_TOKEN" \
  -H 'organizationid: your-organization-id' \
  -H 'Content-Type: application/json' \
  -d '{"name": "Senior Sales Manager"}'

Error Responses

401 Unauthorized

Invalid or missing access token:

{
  "error": "Unauthorized",
  "message": "Invalid or expired access token"
}

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

Use Cases

Map External Roles

Map roles from your identity provider to Sharely roles:

const API_KEY = 'sk-sharely-your-api-key';
const WORKSPACE_ID = 'your-workspace-id';
const ORGANIZATION_ID = 'your-organization-id';
const API_BASE_URL = 'https://api.sharely.ai';
 
// Step 1: Generate access token
async function getAccessToken() {
  const response = await fetch(
    `${API_BASE_URL}/workspaces/${WORKSPACE_ID}/generate-access-key-token`,
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': API_KEY
      },
      body: JSON.stringify({})
    }
  );
  const data = await response.json();
  return data.token;
}
 
// Step 2: Get role by customer role ID
async function getSharelyRole(accessToken, externalRoleId) {
  try {
    const response = await fetch(
      `${API_BASE_URL}/v1/workspaces/${WORKSPACE_ID}/role/by-customer-role-id/${externalRoleId}`,
      {
        headers: {
          'Authorization': `Bearer ${accessToken}`,
          'organizationid': ORGANIZATION_ID
        }
      }
    );
 
    if (response.ok) {
      return await response.json();
    }
    return null;
  } catch (error) {
    console.error('Failed to get role:', error);
    return null;
  }
}
 
// Usage
const accessToken = await getAccessToken();
const role = await getSharelyRole(accessToken, 'sales-manager');

Generate Role-Bound Tokens

Get role details before generating tokens:

async function generateTokenForUser(accessToken, userId, customerRoleId) {
  // Get role details using the access token
  const roleResponse = await fetch(
    `${API_BASE_URL}/v1/workspaces/${WORKSPACE_ID}/role/by-customer-role-id/${customerRoleId}`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'organizationid': ORGANIZATION_ID
      }
    }
  );
  const role = await roleResponse.json();
 
  // Generate token with role (this uses the token generation endpoint with customerRoleId)
  const tokenResponse = await fetch(
    `${API_BASE_URL}/workspaces/${WORKSPACE_ID}/generate-access-key-token`,
    {
      method: 'POST',
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        customerRoleId: role.customerRoleId
      })
    }
  );
 
  return await tokenResponse.json();
}
 
// Usage
const accessToken = await getAccessToken();
const userToken = await generateTokenForUser(accessToken, 'user-123', 'sales-manager');

Verify Role Exists

Check if a role exists before creating:

async function ensureRole(accessToken, customerRoleId, roleData) {
  // Check if exists
  const response = await fetch(
    `${API_BASE_URL}/v1/workspaces/${WORKSPACE_ID}/role/by-customer-role-id/${customerRoleId}`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'organizationid': ORGANIZATION_ID
      }
    }
  );
 
  if (response.ok) {
    console.log('Role already exists');
    return await response.json();
  }
 
  // Create if doesn't exist
  const createResponse = await fetch(
    `${API_BASE_URL}/v1/workspaces/${WORKSPACE_ID}/role`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'organizationid': ORGANIZATION_ID,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        customerRoleId,
        ...roleData
      })
    }
  );
 
  return await createResponse.json();
}
 
// Usage
const accessToken = await getAccessToken();
const role = await ensureRole(accessToken, 'sales-manager', {
  name: 'Sales Manager',
  description: 'Access to sales content'
});

Lookup Table

Build a lookup table for quick access:

async function buildRoleLookup(accessToken, customerRoleIds) {
  const lookup = {};
 
  for (const customerRoleId of customerRoleIds) {
    try {
      const response = await fetch(
        `${API_BASE_URL}/v1/workspaces/${WORKSPACE_ID}/role/by-customer-role-id/${customerRoleId}`,
        {
          headers: {
            'Authorization': `Bearer ${accessToken}`,
            'organizationid': ORGANIZATION_ID
          }
        }
      );
 
      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 accessToken = await getAccessToken();
const roleLookup = await buildRoleLookup(accessToken, [
  'admin',
  'editor',
  'viewer'
]);
// { admin: 'uuid-1', editor: 'uuid-2', viewer: 'uuid-3' }