Authentication

Overview

Authentication for the Semaphor API is performed by generating a secure token using the /api/v1/token endpoint. There are two types of tokens:

• Dashboard Token: Used for embedding dashboards (read-only or self-service). Requires dashboardId and dashboardSecret.
• Project Token: Used for management actions (CRUD on dashboards, visuals, etc.). Requires type: 'project', projectId, and projectSecret.

How to Authenticate

1. Generate a Dashboard Token

Use this for embedding dashboards (read-only or self-service):

curl -X POST https://semaphor.cloud/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "dashboardId": "d_cf007a8b-19bc-46ad-8787-2915445b7b86",
    "dashboardSecret": "ds_f32f0b30-b7e1-40f9-ba6a-9804a5b9d635"
  }'

2. Generate a Project Token

Use this for management actions (CRUD on dashboards, visuals, etc.):

curl -X POST https://semaphor.cloud/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "type": "project",
    "projectId": "p_1234567890abcdef",
    "projectSecret": "ps_abcdef1234567890"
  }'

3. Use the Token

Include the returned accessToken as a Bearer token in the Authorization header for all subsequent API requests:

curl -X GET https://semaphor.cloud/api/management/v1/dashboards \
  -H "Authorization: Bearer <accessToken>"

Security Best Practices

• Never expose your dashboard or project secrets in client-side code or public repositories.
• Always generate tokens on the server side.
• Rotate secrets regularly and monitor API usage for suspicious activity.
• Cache tokens on your server to reduce API calls and avoid rate limits.

Error Handling

Common authentication errors:

Multi-Tenant Applications

For multi-tenant applications, generate dashboard tokens with tenant-specific credentials and fields (e.g., tenantId, endUserId, endUserEmail) as needed. See the Tokens API documentation for details and examples.