Generate Access Key Token

Generate an access token using your workspace API key. This token is used to authenticate subsequent API calls, including provisioning user spaces. Optionally, you can include a role identifier to create a role-bound token that automatically scopes all downstream API operations to that role.

Endpoint

POST /workspaces/{workspaceId}/generate-access-key-token

Authentication

This endpoint requires API key authentication via the x-api-key header. See Authentication for details.

Path Parameters

ParameterTypeRequiredDescription
workspaceIdstring (UUID)YesThe ID of your workspace

Headers

HeaderTypeRequiredDescription
x-api-keystringYesYour workspace API key (format: sk-sharely-...)
Content-TypestringYesMust be application/json

Request Body

FieldTypeRequiredDescription
customerRoleIdstringNoCustom role identifier for RBAC. Must contain only alphanumeric characters, hyphens (-), and underscores (_). Max 255 characters. Mutually exclusive with roleId.
roleIdstring (UUID)NoRole UUID for RBAC. Mutually exclusive with customerRoleId.

Important Notes:

  • You can optionally provide either customerRoleId (string) OR roleId (UUID), but not both
  • If neither is provided, the token will not be role-scoped (full access if RBAC is disabled, or no role filtering)
  • The customerRoleId allows you to use your existing role identifiers without converting them to UUIDs
  • The role must exist in your workspace before generating a token with it

Response

Success Response

Status Code: 200 OK

Body:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response Fields

FieldTypeDescription
tokenstring (JWT)Access token for authenticating subsequent API calls. Valid for 24 hours.

Error Responses

400 Bad Request

Providing both roleId and customerRoleId:

{
  "error": "Bad Request",
  "message": "Provide only one of roleId or customerRoleId"
}

Invalid customerRoleId format:

{
  "error": "Validation Error",
  "message": "customerRoleId must contain only alphanumeric characters, hyphens, and underscores"
}

401 Unauthorized

Invalid API key:

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

404 Not Found

Role not found (when using roleId):

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

Examples

Basic Token Generation (No Role)

curl -X POST \
  'https://api.sharely.ai/workspaces/{workspaceId}/generate-access-key-token' \
  -H 'x-api-key: sk-sharely-your-api-key' \
  -H 'Content-Type: application/json'

With Customer Role ID (Recommended for RBAC)

curl -X POST \
  'https://api.sharely.ai/workspaces/{workspaceId}/generate-access-key-token' \
  -H 'x-api-key: sk-sharely-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "customerRoleId": "sales-manager"
  }'

With Role ID (UUID)

curl -X POST \
  'https://api.sharely.ai/workspaces/{workspaceId}/generate-access-key-token' \
  -H 'x-api-key: sk-sharely-your-api-key' \
  -H 'Content-Type: application/json' \
  -d '{
    "roleId": "550e8400-e29b-41d4-a716-446655440000"
  }'

JavaScript Example

const API_KEY = 'sk-sharely-your-api-key';
const WORKSPACE_ID = 'your-workspace-id';
const BASE_URL = 'https://api.sharely.ai';
 
async function generateAccessToken(customerRoleId = null) {
  const body = customerRoleId ? { customerRoleId } : {};
 
  const response = await fetch(
    `${BASE_URL}/workspaces/${WORKSPACE_ID}/generate-access-key-token`,
    {
      method: 'POST',
      headers: {
        'x-api-key': API_KEY,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(body)
    }
  );
 
  if (!response.ok) {
    throw new Error(`Failed to generate token: ${response.statusText}`);
  }
 
  return await response.json();
}
 
// Generate token without role
const basicToken = await generateAccessToken();
 
// Generate role-bound token
const roleToken = await generateAccessToken('sales-manager');

Python Example

import requests
 
API_KEY = 'sk-sharely-your-api-key'
WORKSPACE_ID = 'your-workspace-id'
BASE_URL = 'https://api.sharely.ai'
 
def generate_access_token(customer_role_id=None):
    body = {'customerRoleId': customer_role_id} if customer_role_id else {}
 
    response = requests.post(
        f'{BASE_URL}/workspaces/{WORKSPACE_ID}/generate-access-key-token',
        headers={
            'x-api-key': API_KEY,
            'Content-Type': 'application/json'
        },
        json=body
    )
    response.raise_for_status()
    return response.json()
 
# Generate token without role
basic_token = generate_access_token()
 
# Generate role-bound token
role_token = generate_access_token('sales-manager')

Token Caching

Access tokens are valid for 24 hours. Consider caching them to reduce API calls:

let cachedToken = null;
let tokenExpiry = null;
 
async function getCachedAccessToken(customerRoleId = null) {
  const cacheKey = customerRoleId || 'default';
 
  if (cachedToken && tokenExpiry && Date.now() < tokenExpiry) {
    return cachedToken;
  }
 
  const response = await generateAccessToken(customerRoleId);
  cachedToken = response.token;
  tokenExpiry = Date.now() + (23 * 60 * 60 * 1000); // 23 hours
 
  return cachedToken;
}

Notes

  • Tokens are valid for 24 hours
  • Role information is embedded in the JWT token
  • Use customerRoleId for human-readable role identifiers
  • Use roleId when you need to reference roles by their UUID
  • The role must exist in your workspace before it can be used

Related Endpoints