Issue session tokens (server)

Sendsar uses a server-authorized model so your secret key never ships to the browser or app. Integrating chat is two steps:

1. Server — Your backend issues a short-lived session token with your API key (sk_*).
2. Client — UI Kit or SDK initializes with that token (Quick start).

This page is step 1: why the mint route exists and how to do it safely. Copy-paste mint samples live in Quick start.

New here?

Run Quick start for the full path (mint → connect → rooms). Come back here for the auth model and guardrails.

Why the server issues the token

	API key (secret)	Session token
Looks like	sk_… in header x-api-key	JWT via Authorization: Bearer … or socket auth.token
Lives on	Your backend only	Browser / mobile after your login
Lifetime	Long-lived (you rotate)	Short (default 1h, max 24h)
Means	Your account	One user in that account

Your server  →  API key (sk_…)     →  issue session tokens + admin API
Your app     →  session token      →  chat as one user

Never put sk_* in a browser, app bundle, or public env. Never use a session token to mint other tokens or change account settings.

“Tenant”

In the API, your account is called a tenant — your Sendsar organization.

Build the token endpoint (BFF)

Goal: Authenticated users of your app get a Sendsar session token — without ever seeing sk_*.

1. Store SENDSAR_API_URL + SENDSAR_API_KEY in server secrets.
2. Expose an authed route (e.g. GET / POST /api/chat/session) behind your login.
3. Derive userId / display name from your session — never trust a client-supplied id.
4. Call POST /v1/auth/token with x-api-key.
5. Return { token, expiresAt, apiUrl, … } to the client.

Mint auto-creates the user when missing. Node / Go / Laravel / curl: Quick start.

# Ops / smoke test only — production apps call YOUR BFF, not this with a browser key
curl -s -X POST "${SENDSAR_API_URL}/auth/token" \
  -H "x-api-key: ${SENDSAR_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{ "userId": "user_abc123", "username": "Alice", "expiresIn": 3600 }'

Env on your server

Variable	Example	Purpose
SENDSAR_API_URL	https://api.sendsar.com/v1	API base
SENDSAR_API_KEY	sk_live_…	Secret — issue tokens + admin
SENDSAR_WEBHOOK_SECRET	whsec_…	Optional — Webhooks

Who can do what

API key (server): issue session tokens · upsert users · admin rooms · tenant settings · push app config.

Session token (client): connect WebSocket · chat as that user · register own device token.

Mismatch userId / senderId vs the token → 403 Cannot act as another user.

Socket auth	Use
auth: { token: "<session token>" }	Production apps
auth: { apiKey: "sk_…" }	Server/debug only — never in end-user apps

Checklist

• [ ] sk_* only on the server
• [ ] Token route behind your app auth
• [ ] userId from your login, not the client body
• [ ] Client gets session token + apiUrl, never sk_*

Common mistakes

Problem	Fix
Secret key in the frontend	Issue tokens on your server only
App calls /auth/token with sk_*	Use your BFF
403 acting as another user	Don’t send a forged userId
Socket stale after refresh	Reconnect with the new session token
401 on admin from the client	Admin calls belong on the server

Next

• Step 2 — Quick start (UI Kit or Client SDK)
• Webhooks · Push notifications
• API Reference