Authentication

The Sharely.ai API uses Bearer token authentication. There are two main authentication flows depending on your use case:

  1. API Key Authentication - For server-to-server integrations and scripts
  2. User Token Authentication - For user-specific operations

API Key Authentication

Obtaining an API Key

To use the Sharely.ai API, you need to generate an API key from your workspace:

  1. Log in to your Sharely.ai dashboard
  2. Navigate to your Workspace Settings
  3. Go to the "API Keys" section
  4. Click "Create New API Key"
  5. Copy your API key immediately - it will only be shown once

Your API key will have the format: sk-sharely-...

Two-Step Authentication Flow

For most /v1/* API endpoints, you'll use a two-step authentication process:

Step 1: Generate Access Token

Exchange your API key for a short-lived access token:

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

Request:

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

Response:

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

Step 2: Use Access Token in API Requests

Use the generated token in the Authorization header:

curl -X GET \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/knowledge' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...' \
  -H 'Content-Type: application/json' \
  -H 'organizationid: your-organization-id'

Note: The organizationid header is required for all /v1/* API requests.

API Key Formats

The Sharely.ai API accepts two types of authentication tokens:

JWT Tokens

Standard JWT tokens generated from your workspace. These are the most common format:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Raw API Keys

Raw API keys with the sk-sharely- prefix (primarily for CAS integration):

Authorization: Bearer sk-sharely-abc123def456...

Both formats are automatically validated and processed by the API.

Alternative Authentication Header

Some V1 API endpoints (particularly the Roles API) support an alternative authentication header format using x-api-key:

x-api-key: sk-sharely-abc123def456...

This header accepts raw API keys without the "Bearer" prefix. Both authentication methods are functionally equivalent - use whichever is more convenient for your integration.

Example with x-api-key header:

curl -X GET \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/role' \
  -H 'x-api-key: YOUR_API_KEY'

Workspace ID

Most API endpoints require a workspaceId parameter in the URL path. You can find your workspace ID in your dashboard settings or by listing your workspaces via the API.

Example endpoint:

/v1/workspaces/{workspaceId}/knowledge

Replace {workspaceId} with your actual workspace UUID.

API Versioning

All v1 API responses include an X-API-Version header:

X-API-Version: v1

This header helps you identify which version of the API processed your request.

Security Best Practices

Keep Your API Key Secret

  • Never commit API keys to version control
  • Don't expose API keys in client-side code
  • Use environment variables to store keys
  • Rotate keys regularly

Use HTTPS

All API requests must use HTTPS. HTTP requests will be rejected.

Scope Your Keys

Create separate API keys for different applications or environments (development, staging, production) to minimize security risks.

Revoke Compromised Keys

If an API key is exposed or compromised, revoke it immediately from your workspace settings and generate a new one.

Authentication Errors

401 Unauthorized

Your API key is missing, invalid, or expired.

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

Solution: Check that your Authorization header is correctly formatted and contains a valid API key.

403 Forbidden

Your API key is valid, but you don't have permission to access the requested resource.

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

Solution: Verify that your API key has the necessary permissions for the workspace you're trying to access.

Testing Your Authentication

You can test your API key by making a simple GET request to list categories:

curl -X GET \
  'https://api.sharely.ai/v1/workspaces/{workspaceId}/categories' \
  -H 'Authorization: Bearer YOUR_API_KEY'

A successful response confirms your API key is working correctly.

User Space Activation API

When integrating Sharely.ai with your application (e.g., using JSWebControl), you may need to activate or retrieve a user space with specific role-based access control (RBAC) settings.

Activate or Retrieve User Space

This endpoint creates or retrieves a user space with optional role assignment:

POST /workspaces/{workspaceId}/activate-or-retrieve-user-space-api-key

Request:

curl -X POST \
  'https://api.sharely.ai/workspaces/{workspaceId}/activate-or-retrieve-user-space-api-key' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "userId": "user-123",
    "email": "user@example.com",
    "customerRoleId": "physician"
  }'

Request Parameters:

  • userId (required): Unique identifier for the user
  • email (required): User's email address
  • customerRoleId (optional): External role identifier to assign to the user

Response:

{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user": {
    "id": "user-123",
    "email": "user@example.com"
  },
  "space": {
    "id": "space-uuid",
    "workspaceId": "workspace-uuid"
  }
}

The returned token includes user_metadata.roleId which is automatically mapped from the customerRoleId you provided. This token can be used to initialize JSWebControl with proper RBAC filtering.

Use Case: This is particularly useful for applications like PrecisionCare that need to:

  1. Create or retrieve a space for a specific user
  2. Assign a role (e.g., "physician", "nurse") to that user
  3. Initialize JSWebControl with a token that includes the role information

Next Steps

Once you have your API key configured, you can start making API calls: