Authentication

The core API has no single login. Each lane in src/modules/index.ts has its own middleware and its own credential. This page walks through all of them. The lane table and mount map are on the API overview. All secrets below are placeholders. Never commit real values.

Web gateway lane

Prefix: /v1/web/*. Middleware: requireServiceAuth (packages/security), then webUserContext (src/middleware/web-context.ts), then the web rate limiter. The coach web app never lets the browser call the core API. Its server signs each request with the shared secret SERVICE_AUTH_SECRET and forwards the user it already authenticated with better-auth as plain headers. The headers are trusted only because the signature proves the caller is the web app.

Service signature

Header	Value
`x-service-id`	Service name. The API only knows `web` (`serviceSecrets = { web: SERVICE_AUTH_SECRET }` in `server.ts`). The web app reads it from `CORE_API_SERVICE_ID`, default `web`
`x-timestamp`	`Date.now()` as a string, in milliseconds
`x-nonce`	A fresh random value per request. The clients use `randomUUID()`
`x-signature`	Hex HMAC-SHA256 of the canonical string

Hash the body

bodyHash = sha256Hex(rawBodyBytes). For a request with no body, hash the empty string. The server hashes req.rawBody, the exact bytes it received, so serialize JSON once and send that same string.

Build the canonical string

Join five values with a newline: the upper-case method, the path, the timestamp, the nonce and the body hash. The path is req.originalUrl on the server, so it includes /v1/web/... and the query string exactly as sent.

Sign

signature = HMAC-SHA256(SERVICE_AUTH_SECRET, canonical) as lower-case hex.

Send

Add the four headers and the user context headers below.

import { createHash, createHmac, randomUUID } from 'node:crypto';

const body = JSON.stringify({ name: 'Dana Levi' });
const path = '/v1/web/clients?page=1';
const timestamp = String(Date.now());
const nonce = randomUUID();
const bodyHash = createHash('sha256').update(body).digest('hex');
const canonical = ['POST', path, timestamp, nonce, bodyHash].join('\n');
const signature = createHmac('sha256', process.env.SERVICE_AUTH_SECRET!)
  .update(canonical)
  .digest('hex');

The reference implementations are createServiceClient in backend/packages/security/src/index.ts and coreApiRequest in frontend/apps/saas/modules/shared/lib/core-api.ts. The server checks, in this order: all four headers present, a known x-service-id, a timestamp within 300,000 ms of server time in either direction, a matching signature (compared with timingSafeEqual), and a nonce that has not been used. Nonces are stored in Redis under perform:nonce:<nonce> with SET NX and a TTL of 360 seconds.

Failure	Status	Code	Message
A header is missing	401	`UNAUTHORIZED`	`missing service auth headers`
Unknown `x-service-id`	401	`UNAUTHORIZED`	`unknown service`
Timestamp outside the window	401	`UNAUTHORIZED`	`stale or invalid timestamp`
Signature mismatch	401	`UNAUTHORIZED`	`invalid service signature`
Nonce seen before	401	`UNAUTHORIZED`	`nonce already used`

User context headers

Header	Required	Value
`x-studio-id`	Yes	The better-auth organization id. Mapped to `Studio.externalOrgId`
`x-user-id`	Yes	The better-auth user id of the acting coach
`x-user-role`	No	`OWNER`, `HEAD_COACH`, `SUB_COACH` or `TRAINEE`. Anything else, or a missing header, becomes `SUB_COACH`
`x-studio-name`	No	URI-encoded studio name. Used when the studio row has to be created or linked
`x-studio-slug`	No	URI-encoded slug, same use
`x-user-name`	No	URI-encoded user name, used when the owner’s coach row is created
`x-user-email`	No	User email, same use. A few routes read it directly

webUserContext does more than read headers:

It resolves the studio by externalOrgId. If none matches, it looks for a studio with the same slug and links it. If there is still none, it creates the studio with the default content categories. The result is cached in memory per organization id.
When the role is OWNER, it upserts a Coach row with role HEAD_COACH for that user, once per process.
It stamps Coach.lastActiveAt at most once every 5 minutes per coach.
It sets req.auth = { studioId, userId, role }, where studioId is the internal Studio.id, not the organization id.

A missing x-studio-id or x-user-id returns 401 UNAUTHORIZED with missing web user context.

curl -X POST 'https://perform-api.otherwise.co.il/v1/web/clients?page=1' \
  -H 'content-type: application/json' \
  -H 'x-service-id: web' \
  -H 'x-timestamp: 1791369600000' \
  -H 'x-nonce: 6d0f6c1e-3b0a-4c63-9d7e-2f4d6b1a9c55' \
  -H 'x-signature: YOUR_COMPUTED_SIGNATURE' \
  -H 'x-studio-id: org_2aB3cD4eF5' \
  -H 'x-user-id: usr_9xY8wV7uT6' \
  -H 'x-user-role: OWNER' \
  -d '{"name":"Dana Levi"}'

Roles and coach permissions

Role checks inside web routers use requireRole(...roles) from src/middleware/require-role.ts. It returns 401 authentication required when req.auth is missing and 403 FORBIDDEN with insufficient role when the role is not listed. Some routers also resolve a per-coach permission set with withCoachAccess or requireAssignedClient (src/middleware/coach-access.ts). The rules in coachAccessFrom:

OWNER always has full access.
A Coach row with active = false is refused with 403 this team member has been removed.
A caller with no Coach row keeps studio-wide access.
Otherwise the stored permissions blob decides. When permissions.trainees is not all, the coach only reaches trainees assigned to them through Client.coachAssignments, and any other client id returns 404 client not found.

Internal and admin lane

Prefix: /v1/internal/*, /v1/admin/default-forms, /v1/admin/notification-configs. Middleware: requireServiceAuth only. Same four signature headers as the web gateway, but no user context and no req.auth. These routes act on whatever ids the body carries, so they must only ever be called by the web app server. See Internal endpoints.

Trainee lane

Prefix: /v1/trainee/*. Middleware: authenticateTrainee and, on most routes, requireTraineeAppAccess (src/middleware/trainee-auth.ts). The app signs in with a WhatsApp one-time code and receives a trainee token. The full flow is on Trainee sign-in.

GET /v1/trainee/home HTTP/1.1
Host: perform-api.otherwise.co.il
Authorization: Bearer YOUR_TRAINEE_TOKEN
x-timezone: Asia/Jerusalem
x-app-platform: ios

Header	Required	Purpose
`Authorization`	Yes	`Bearer` plus the trainee token
`x-timezone`	No	The device’s IANA time zone. A valid value is saved to `Client.timezone` and decides what “today” means for this trainee. Ignored for preview tokens
`x-app-platform`	No	`ios` or `android`. Read by sign-in, `me`, `home` and `app-release`

The token is not a JWT and not a better-auth session. trainee.token.ts builds it as base64url(JSON payload) + "." + base64url(HMAC-SHA256(payload, BETTER_AUTH_SECRET)). The payload holds clientId and studioId. Regular tokens carry no expiry. Preview tokens carry preview: true and an exp 15 minutes ahead. The mobile app also sends X-Timestamp and X-Nonce on its requests. The trainee lane does not read them. Replay protection is only mounted in front of the bearer lane.

What `authenticateTrainee` checks

Failure	Status	Code	Message or reason
No bearer token	401	`UNAUTHORIZED`	`authentication required`
Bad signature, malformed token or expired preview token	401	`UNAUTHORIZED`	`invalid or expired session`
Preview token on a non-GET request	403	`FORBIDDEN`	`details.reason = "PREVIEW_READ_ONLY"`
The studio is archived (`Studio.deletedAt` set)	401	`UNAUTHORIZED`	`studio no longer exists`

The studio check is cached in memory for 30 seconds per studio. Because tokens never expire, this check is how archiving a studio reaches sessions that already exist.

What `requireTraineeAppAccess` checks

This second guard is named access in trainee.routes.ts. It loads planFrozenOn, appAccessWhileFrozen, endsOn and the live subscriptions, cached for 30 seconds per client.

Failure	Status	Code	Message or reason
Client row missing, client deleted or studio deleted	401	`UNAUTHORIZED`	`account no longer exists`
Subscription frozen or ended, and `appAccessWhileFrozen` is not `true`	403	`FORBIDDEN`	`app access is paused`, `details.reason = "APP_LOCKED"`

“Ended” uses coverageEndsOn, so a plan queued behind the running one keeps the app open. A trainee with no end date and no freeze is never locked. Not every trainee route uses access. Sign-in, GET /v1/trainee/me, DELETE /v1/trainee/me, GET /v1/trainee/app-release and the push token routes only use authenticateTrainee, so a locked trainee can still load the lock screen and delete their account. The smaller trainee routers (forms, uploads, calendar, content, shopping, foods, notification settings) also mount authenticateTrainee only. The forms service applies its own frozen-plan rule.

Partner and automation lanes

Prefix: /v1/partner/* and /v1/automation/*. Middleware: requirePartnerKey (src/modules/partner/partner-auth.ts). Both lanes use a studio API key. A coach with role OWNER or HEAD_COACH creates it through POST /v1/web/studios/current/api-keys. The key is pf_live_ followed by 40 hex characters (20 random bytes). Only its SHA-256 hash is stored in StudioApiKey.keyHash, along with the first 15 characters as prefix for display. The plain key is returned once, in the create response.

curl 'https://perform-api.otherwise.co.il/v1/automation/validate' \
  -H 'Authorization: Bearer YOUR_API_KEY'

The middleware hashes the presented key, looks it up, and sets req.partner = { studioId, apiKeyId }. Every query in both lanes is scoped to that studio. There are no scopes on a key: any valid key can call every endpoint in both lanes. lastUsedAt is updated at most once every 5 minutes per key.

Failure	Status	Message
No bearer value, or it does not start with `pf_live_`	401	`missing partner api key`
Unknown key, revoked key, or the studio is archived	401	`invalid partner api key`

The error body differs by lane. /v1/partner uses the standard error envelope. /v1/automation uses { "success": false, "message": "..." }. See Partner API and Automation API. The MCP endpoint accepts the same key and calls /v1/automation on the caller’s behalf.

Public lane

/v1/public/waitlist-leads and /v1/public/onboarding/* take no credential. They rely on rate limits and, for the onboarding OTP, on per-phone and per-IP throttles. See Public endpoints. /v1/public/sign/:token is the public signing page for documents to sign. The 128-bit token in the path is the credential. Two callers reach it:

A browser or script calling the API directly. It is counted by the global /v1 limiter under its own IP.
The web app’s proxy. It sends x-service-id, so the router requires a valid service signature, and in return the request skips the global limiter and the proxy’s x-client-ip header is believed as the visitor address.

A request that sends x-service-id without a valid signature is refused with 401. The lane has its own per-link and per-IP counters, listed on Conventions.

Webhook lane

POST /v1/whatsapp/webhook/:studioId and POST /v1/agent/webhook are called by SmartSend. There is no signature and no bearer token. The caller appends ?token=... and the API compares it to SMARTSEND_WEBHOOK_SECRET with timingSafeEqual (verifyWebhookToken in packages/smartsend). A missing or wrong token, or an unset secret, returns 401 UNAUTHORIZED with invalid webhook token.

curl -X POST 'https://perform-api.otherwise.co.il/v1/agent/webhook?token=YOUR_WEBHOOK_TOKEN' \
  -H 'content-type: application/json' \
  -d '{"text":"hello","phone":"972500000000","conversationId":"conv_123","senderName":"Dana"}'

The payments provider webhook is separate. It is POST /api/webhooks/payments, handled by @repo/payments inside the Hono app, and verified by that package.

Bearer lane

Prefix: /v1/studios, /v1/clients, /v1/whatsapp. Middleware: replayProtection, then authenticate. Replay protection requires x-nonce and x-timestamp. Missing headers return 400 BAD_REQUEST with missing x-nonce or x-timestamp header. A timestamp outside 300 seconds or a reused nonce returns 401. authenticate reads Authorization: Bearer <session token> and resolves it through better-auth. With SESSION_VERIFY_INPROCESS set it calls auth.api.getSession in the same process. Otherwise it fetches BETTER_AUTH_URL/api/auth/get-session. The session’s activeOrganizationId becomes studioId and the member role maps owner to OWNER, admin to HEAD_COACH, and anything else to SUB_COACH.

req.auth.studioId on this lane is the better-auth organization id as returned by the session. On the web gateway lane it is the internal Studio.id resolved by webUserContext. The same routers are mounted on both. No current client in the three repos was found calling the bearer mounts, and packages/auth/src/auth.ts does not register better-auth’s bearer plugin, so treat this lane as unverified before building on it.

better-auth sessions

Coach sign-in, organizations, passkeys and two-factor all go through better-auth at /api/auth/*. The web app keeps the session cookie and never sends it to /v1. See Auth endpoints.

Quick reference

Lane	Send	Verified by
Web gateway	`x-service-id`, `x-timestamp`, `x-nonce`, `x-signature`, `x-studio-id`, `x-user-id`, `x-user-role`	`requireServiceAuth`, `webUserContext`
Internal and admin	`x-service-id`, `x-timestamp`, `x-nonce`, `x-signature`	`requireServiceAuth`
Trainee	`Authorization: Bearer <trainee token>`, optional `x-timezone`, `x-app-platform`	`authenticateTrainee`, `requireTraineeAppAccess`
Partner and automation	`Authorization: Bearer pf_live_...`	`requirePartnerKey`
MCP	`Authorization: Bearer pf_live_...`	Prefix check in `mcpRouter`, then `requirePartnerKey` on the internal call
Public signing	Token in the path	`form-sign.service` lookup and throttles
Webhooks	`?token=...`	`verifyWebhookToken`
Bearer	`Authorization: Bearer <session token>`, `x-timestamp`, `x-nonce`	`replayProtection`, `authenticate`

API basics

Trainees

Plans and libraries

Tracking

Imports

Forms

Tasks and automation

Communication

Studio and billing

Admin and internal services

Trainee app API

Partner and automation

Public, internal and auth

Web gateway lane

Service signature

User context headers

Roles and coach permissions

Internal and admin lane

Trainee lane

What `authenticateTrainee` checks

What `requireTraineeAppAccess` checks

Partner and automation lanes

Public lane

Webhook lane

Bearer lane

better-auth sessions

Quick reference

​Web gateway lane

​Service signature

​User context headers

​Roles and coach permissions

​Internal and admin lane

​Trainee lane

​What authenticateTrainee checks

​What requireTraineeAppAccess checks

​Partner and automation lanes

​Public lane

​Webhook lane

​Bearer lane

​better-auth sessions

​Quick reference

Web gateway lane

Service signature

User context headers

Roles and coach permissions

Internal and admin lane

Trainee lane

What `authenticateTrainee` checks

What `requireTraineeAppAccess` checks

Partner and automation lanes

Public lane

Webhook lane

Bearer lane

better-auth sessions

Quick reference