Create an auth token

Generates a signed access token for embedding a dashboard or accessing a project. Choose a scenario from the table below:

Token type	Scenario	Required fields	Use case
`dashboard`	Single dashboard	`dashboardId`, `dashboardSecret`	Embed one dashboard; no user management needed
`project`	Org user	`projectId`, `projectSecret`, `orgUserId`	Your organization's internal users accessing multiple dashboards
`project`	Tenant user by ID	`projectId`, `projectSecret`, `endUserId`	Customer already provisioned in Semaphor
`project`	Tenant user by email	`projectId`, `projectSecret`, `endUserEmail`, `tenantId` or `tenantName`	Customer identified by email and tenant
`project`	Auto-provision user	`projectId`, `projectSecret`, `endUserEmail`, `tenantId` or `tenantName`, `autoCreateEndUser: true`	New customers created automatically on first access

For auto-provisioning, the new user is assigned the role you specify (defaults to VIEWER).

Dashboard selection (project tokens only): The dashboard loaded on first render is resolved in priority order:

Priority	Field	Behavior
1	`targetDashboardId`	Hard navigation — always wins
2	(user preference)	User's saved preference for this project
3	`initialDashboardId`	Soft default — overridden by user preference
4	(project default)	The project's default dashboard

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

dashboardId*string

The ID of the dashboard to embed. Find this in the dashboard settings or via the Dashboard API.

dashboardSecret*string

The shared secret for this dashboard. Generated when the dashboard is created and available in dashboard settings.

type?string

Token type. Set to "dashboard" for a single-dashboard token or "project" for multi-dashboard access. Defaults to "dashboard" when omitted.

Value in"dashboard" | "project"

orgUserId?string

Organization user ID. Use this to identify an internal (org-level) user accessing the dashboard or project.

orgUserEmail?string

Organization user email. Used for identity resolution and audit trails.

Formatemail

endUserId?string

Tenant user ID for an existing end user. Use this when you already know the user's Semaphor ID.

endUserEmail?string

Tenant user email. Used together with tenantId or tenantName to look up the user, or to create them on-the-fly when autoCreateEndUser is true.

Formatemail

tenantId?string

Tenant identifier. Required when using endUserEmail for user lookup or auto-provisioning.

tenantName?string

Tenant name (alternative to tenantId). The server resolves this to a tenant ID. Available for project tokens only.

displayName?string

Display name embedded in the token for personalization and audit. For auto-provisioned users, this becomes their initial display name (defaults to the email prefix if omitted).

autoCreateEndUser?boolean

When true, automatically creates the tenant user if endUserEmail lookup finds no match. The new user is assigned the role from role (defaults to VIEWER). Display name defaults to the email prefix if omitted. Project tokens only.

The tenant must already exist -- new tenants are not created. If autoCreateEndUser is false or omitted and the user is not found, the request returns an error.

role?string

Role assigned to auto-provisioned tenant users. Defaults to VIEWER if omitted. Project tokens only.

Value in"VIEWER" | "POWER_USER"

tokenExpiry?number

Token lifetime in seconds. Defaults to 8 hours (28800s) when omitted.

securityParams?

Runtime placeholder values for Unified Security policies. Keys are placeholder names defined in your security policy templates; values are the runtime values to substitute.

This is the preferred way to pass security context for new integrations. Values can be strings, numbers, booleans, or arrays.

secretSecurityParams?

Secret runtime values for Unified Security placeholders. Use this for values that should not be persisted in reusable assignment records (e.g., database passwords, API keys).

Secret values are converted to secure references in the token -- the actual values are stored server-side and resolved at query time.

semanticDomainAccess?

Controls which semantic domains the token holder can access. Use this to restrict or grant access to specific data domains within the project.

params?

Formatting and calendar preferences for the token. These control how dates, numbers, and currencies are displayed in dashboards.

config?

UI feature flags that control which capabilities are available in the embedded dashboard.

cls?|array<>Deprecated

Deprecated. Legacy connection-level security policy references. Use Unified Security with securityParams and secretSecurityParams instead.

Accepts a single policy object or an array of policies. Still functional for backward compatibility.

rcls?|array<>Deprecated

Deprecated. Legacy row-level security policy references. Use Unified Security with securityParams and secretSecurityParams instead.

Accepts a single policy object or an array of policies. Still functional for backward compatibility.

sls?stringDeprecated

Deprecated. Legacy schema-level security override. Use Unified Security with securityParams and secretSecurityParams instead.

Still functional for backward compatibility. Project tokens only.

allowedSemanticDomains?array<string>Deprecated

Deprecated. Use semanticDomainAccess instead. An empty array is treated as { mode: "none" }. A non-empty array is treated as { mode: "include", domains: [...] }.

projectId*string

The ID of the project to access. Find this in the project settings or via the Management API.

projectSecret*string

The shared secret for this project. Generated when the project is created and available in project settings.

type?string

Optional. Project mode is also inferred automatically when both projectId and projectSecret are present.

Value in"project"

initialDashboardId?string

Soft default dashboard to load first. The user's saved preference takes priority over this value.

targetDashboardId?string

Hard navigation target. Always loads this dashboard, regardless of user preferences or project defaults.

orgUserId?string

Organization user ID. Use this to identify an internal (org-level) user accessing the dashboard or project.

orgUserEmail?string

Organization user email. Used for identity resolution and audit trails.

Formatemail

endUserId?string

Tenant user ID for an existing end user. Use this when you already know the user's Semaphor ID.

endUserEmail?string

Tenant user email. Used together with tenantId or tenantName to look up the user, or to create them on-the-fly when autoCreateEndUser is true.

Formatemail

tenantId?string

Tenant identifier. Required when using endUserEmail for user lookup or auto-provisioning.

tenantName?string

Tenant name (alternative to tenantId). The server resolves this to a tenant ID. Available for project tokens only.

displayName?string

Display name embedded in the token for personalization and audit. For auto-provisioned users, this becomes their initial display name (defaults to the email prefix if omitted).

autoCreateEndUser?boolean

The tenant must already exist -- new tenants are not created. If autoCreateEndUser is false or omitted and the user is not found, the request returns an error.

role?string

Role assigned to auto-provisioned tenant users. Defaults to VIEWER if omitted. Project tokens only.

Value in"VIEWER" | "POWER_USER"

tokenExpiry?number

Token lifetime in seconds. Defaults to 8 hours (28800s) when omitted.

securityParams?

Runtime placeholder values for Unified Security policies. Keys are placeholder names defined in your security policy templates; values are the runtime values to substitute.

This is the preferred way to pass security context for new integrations. Values can be strings, numbers, booleans, or arrays.

secretSecurityParams?

Secret runtime values for Unified Security placeholders. Use this for values that should not be persisted in reusable assignment records (e.g., database passwords, API keys).

Secret values are converted to secure references in the token -- the actual values are stored server-side and resolved at query time.

semanticDomainAccess?

Controls which semantic domains the token holder can access. Use this to restrict or grant access to specific data domains within the project.

params?

Formatting and calendar preferences for the token. These control how dates, numbers, and currencies are displayed in dashboards.

config?

UI feature flags that control which capabilities are available in the embedded dashboard.

cls?|array<>Deprecated

Deprecated. Legacy connection-level security policy references. Use Unified Security with securityParams and secretSecurityParams instead.

Accepts a single policy object or an array of policies. Still functional for backward compatibility.

rcls?|array<>Deprecated

Deprecated. Legacy row-level security policy references. Use Unified Security with securityParams and secretSecurityParams instead.

Accepts a single policy object or an array of policies. Still functional for backward compatibility.

sls?stringDeprecated

Deprecated. Legacy schema-level security override. Use Unified Security with securityParams and secretSecurityParams instead.

Still functional for backward compatibility. Project tokens only.

allowedSemanticDomains?array<string>Deprecated

Deprecated. Use semanticDomainAccess instead. An empty array is treated as { mode: "none" }. A non-empty array is treated as { mode: "include", domains: [...] }.

Response Body

`application/json`

curl -X post "https://semaphor.cloud/api/v1/token" \  -H "Content-Type: application/json" \  -d '{    "dashboardId": "d_abc123",    "dashboardSecret": "dash_secret_123",    "endUserEmail": "user@example.com",    "tenantId": "tenant_123",    "semanticDomainAccess": {      "mode": "include",      "domains": [        "sales",        "finance_domain"      ]    }  }'

{
  "accessToken": "string"
}

{
  "error": "string"
}

{
  "error": "string"
}

{
  "error": "string"
}

Create an auth token

Request Body

Response Body

200application/json

400application/json

404application/json

500application/json

`application/json`

`application/json`

`application/json`

`application/json`