Token Integration

When a connection uses Unified Security, the token request shifts from carrying security policy details to identifying who the user is. Admins define the policies; the token tells Semaphor which actor to resolve them for.

This page covers how to structure token requests for connections in unified mode. For the complete request contract, see the Token API.

What Changes in Unified Mode

In legacy mode, your token request carries security policies (cls, rcls, sls) with concrete parameter values. In unified mode, those policies live on the server as policy definitions and assignments.

Your token request needs to provide:

1. Actor identity -- who is this user? (tenantId, endUserId, orgUserId)
2. Security params (optional) -- runtime-owned values for supported {{ placeholder }} parameters, via the securityParams field

That's it. Semaphor resolves the effective security context from persisted assignments plus any securityParams you supply.

Actor Identification

The token request identifies the actor using the same fields as before. Semaphor derives the actor type from the fields you provide, checked in this order:

If none of these fields are present on a unified connection, the request fails with: "Unified Security requires an organization, tenant, or tenant user actor context."

These fields work on both dashboard tokens and project tokens. See Token API for the complete field reference.

Integration Scenarios

Scenario 1: Fully Admin-Managed (Recommended)

The admin creates policy definitions and assignments with all parameter values bound. Your token request only needs actor identity.

const TOKEN_URL = 'https://semaphor.cloud/api/v1/token';

const requestBody = {
  type: 'project',
  projectId: PROJECT_ID,
  projectSecret: PROJECT_SECRET,
  tenantId: 'tenant_acme',       
  endUserId: 'user_jane',        
  // No cls, rcls, sls, or security params needed.
  // Admin configured everything via policy definitions and assignments.
};

async function fetchToken() {
  const response = await fetch(TOKEN_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(requestBody),
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  const token = await response.json();
  return token;
}

This is the simplest integration — and the recommended approach for most use cases. The admin manages all security values centrally, and your code has zero security logic.

Scenario 2: Admin Policy Definitions + Runtime Security Params

When some values genuinely vary per request and can't be pre-configured in assignments, you can supply them at token time via the securityParams field. The admin creates the policy structure and binds stable values in assignments; your code fills in the dynamic ones.

For example, the admin declares tenant_id as assignment-owned and declares region and department as token-owned because they change per session.

const requestBody = {
  type: 'project',
  projectId: PROJECT_ID,
  projectSecret: PROJECT_SECRET,
  tenantId: 'tenant_acme',
  endUserId: 'user_jane',
  securityParams: {                   
    region: 'west',                   
    department: 'engineering',        
  },                                  
};

async function fetchToken() {
  const response = await fetch(TOKEN_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(requestBody),
  });

  if (!response.ok) {
    throw new Error(`HTTP error! status: ${response.status}`);
  }

  return await response.json();
}

For persisted RLS, these keys fill only parameters declared with source: TOKEN. Parameter ownership is deterministic; Semaphor does not inspect SQL to decide whether a token value narrows or widens access.

Scenario 3: No Applicable Assignment

If an actor has no applicable assignment, that actor does not receive the corresponding persisted policy definition.

const requestBody = {
  type: 'project',
  projectId: PROJECT_ID,
  projectSecret: PROJECT_SECRET,
  tenantId: 'tenant_new_customer',
  endUserId: 'user_bob',
  // This actor has no assignments yet.
  // No persisted Unified Security definition is applied for this actor.
};

This does not mean the actor has unrestricted product access. Connection permissions, database grants, legacy or token-only security where applicable, and other authorization controls remain independent.

The securityParams Field

In unified mode, the securityParams field supplies supported runtime parameter values. For persisted RLS, the definition must explicitly declare each supplied key with source: TOKEN.

const requestBody = {
  type: 'project',
  projectId: PROJECT_ID,
  projectSecret: PROJECT_SECRET,
  tenantId: 'tenant_acme',
  endUserId: 'user_jane',
  securityParams: {                   
    department: 'sales',              // fills {{ department }} placeholder
    access_tier: 'standard',          // fills {{ access_tier }} placeholder
  },                                  
};

Each key in securityParams matches a {{ placeholder }} name in the policy definition. If the placeholder uses @secret, see the next section for how secrets are handled.

Secret Parameters (@secret)

Policy definitions can mark sensitive placeholders with an @secret suffix -- for example, {{ password@secret }} in a CLS connection template. Secret values are passed in a separate secretSecurityParams field on the token request, not in securityParams. Semaphor encrypts them server-side so the plaintext never appears in the signed JWT.

How it works

1. You send the plaintext secret in the secretSecurityParams field, using the plain key name (without the @secret suffix).
2. Non-secret values go in securityParams as usual.
3. Semaphor validates the secret against applicable CLS templates, stores it server-side, and replaces it with an opaque lookup reference.
4. The signed JWT carries the reference, not the plaintext secret.
5. At query time, Semaphor resolves the real secret server-side when rendering the CLS template.

The plaintext secret is never embedded in the token payload.

Example

Given this CLS policy definition:

{
  "connectionTemplate": "postgresql://{{ username }}:{{ password@secret }}@db.example.com/app"
}

Your token request separates plain values from secrets:

const response = await fetch('https://semaphor.cloud/api/v1/token', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    type: 'project',
    projectId: PROJECT_ID,
    projectSecret: PROJECT_SECRET,
    tenantId: 'tenant_acme',
    endUserId: 'user_123',
    securityParams: {                                  
      username: 'analytics_user',                      
    },                                                 
    secretSecurityParams: {                            
      password: 'super-secret-db-password',            
    },                                                 
  }),
});

The resulting JWT payload contains a reference for the secret, not the plaintext:

{
  "type": "project",
  "project_id": "p_123",
  "tenantId": "tenant_acme",
  "endUserId": "user_123",
  "securityParams": {
    "username": "analytics_user",
    "password": "9c4d2c91-5f2a-4d8d-b6d0-3d6d1d5d4e11"
  }
}

Notice that both values end up under securityParams in the JWT -- but the password is an opaque reference, not the plaintext. At query time, Semaphor resolves 9c4d2c91-... back to the real password server-side and renders the connection string.

Dashboard Tokens vs Project Tokens

Both token types work with Unified Security. The difference is scope, not security behavior.

When a project has some connections in legacy mode and others in unified mode, both are handled correctly within the same token. Each connection resolves security independently based on its own mode.

What NOT to Do

// This will fail on unified connections
const requestBody = {
  type: 'project',
  projectId: PROJECT_ID,
  projectSecret: PROJECT_SECRET,
  tenantId: 'tenant_acme',
  endUserId: 'user_jane',
  cls: {                              
    name: 'store_sales_primary',      
    params: { tenant: 'acme' },       
  },                                  
  rcls: {                             
    name: 'region_filter',            
    params: { state: ['California'] },
  },                                  
};

If you need legacy security fields for some connections, keep those connections in legacy mode. Per-connection mode switching lets you migrate incrementally.

Best Practices

• Bind stable values in assignments. If a value is fixed per actor — database name, tenant ID, schema — put it in the assignment. This keeps your token code simple and gives admins centralized control over security configuration.
• Use securityParams for genuinely dynamic values. Values that change per request or per session (e.g., a user-selected region filter, a time-scoped access window) are a good fit for securityParams. There is no performance penalty for plain security params — they pass through to the token without additional processing.
• Prefer assignment-bound secrets over token-time secrets. Secret parameters (@secret) passed via secretSecurityParams require server-side encryption and storage on every token request. Binding secrets in assignments avoids this per-request overhead and keeps sensitive values out of your application code entirely.

Error Reference

Common errors when using Unified Security with tokens:

Migration Checklist

When moving a connection from legacy to unified:

1. Create policy definitions with the same policy logic you had in token-based CLS/RCLS/SLS.
2. Create assignments for each actor, binding the parameter values that were previously in your token requests.
3. Use Security preview to verify each actor's effective security matches your expectations.
4. Remove cls, rcls, and sls fields from your token generation code. Move any runtime security values to securityParams.
5. Switch the connection to unified mode.
6. Test with each actor type to confirm correct behavior.

For a detailed migration walkthrough, see the Migration Guide.

Next Steps

• Security Overview -- how Unified Security works
• Policy Types -- CLS, SLS, and RLS configuration details
• Policy Definitions & Assignments -- create and manage policy definitions
• How Row-Level Security Works -- understand RLS parameter ownership
• Automate with the API -- automate validation and preview
• Token API -- full token API field reference