Authentication
Tahlib runs its own sign-in: email and password, or Google. There is no third-party identity provider in the request path.
Session bearer tokens
Authenticated routes take a short-lived access token:
Authorization: Bearer <access token>The access token is an HS256 JWT signed by the API. It lasts 15 minutes by
default (AUTH_ACCESS_TTL). Its sub claim is the user id and it also
carries email. It does not name a restaurant: the restaurant is resolved
on each request (see Choosing the restaurant).
Getting a token
Sign in with POST /v1/auth/login:
{ "email": "owner@example.com", "password": "…" }A successful sign-in returns the user and an access token:
{ "user": { "id": "…", "email": "owner@example.com", "…": "…" }, "accessToken": "eyJ…" }and sets an HTTP-only tahlib_session cookie holding the refresh token.
Sessions last 30 days by default (AUTH_REFRESH_TTL_DAYS).
| Route | What it does |
|---|---|
POST /v1/auth/signup | Create an account. Returns needsVerification: true instead of a token when the email must be verified first. |
POST /v1/auth/login | Email and password. 403 email_not_verified until the email is verified, when verification is required. |
POST /v1/auth/google | Exchange a Google ID token ({ "idToken": "…" }). |
POST /v1/auth/refresh | New access token from the tahlib_session cookie. 401 session_expired when the session has ended. |
POST /v1/auth/logout | End the current session. |
GET /v1/auth/me | The signed-in user, their role and permissions at the resolved restaurant. |
GET /v1/auth/sessions | The user's active sessions. |
POST /v1/auth/sign-out-all | End every session for the user. |
Wrong credentials return 401 invalid_credentials. Rate limits on these
routes are listed in the overview.
Browser origins
The /v1/auth/* routes refuse browser requests from any origin other than
the Tahlib staff apps, answering 403 origin_not_allowed. Server-side calls,
which send no Origin header, are not affected.
Roles and permissions
A valid token proves who the user is. What they may do is decided per
restaurant by their staff role: each staff route requires a permission such
as orders.view or settings.edit, and a missing one returns 403
permission_denied (shape in the overview).
GET /v1/auth/me returns the caller's permissions. Treat that list as a
hint for what to show; the API still checks every call.
API keys
API keys are for a restaurant's own integration. They work on the read-only
integration API (/v1/integration/*) and nowhere else: every other
route on these pages needs a session bearer token.
Managing keys (in the dashboard: Settings → API keys):
| Route | Requires |
|---|---|
GET /v1/api-keys | settings.view permission, Advanced API & Webhooks product (webhooks module) |
POST /v1/api-keys | settings.edit permission, webhooks module; 5 per minute |
POST /v1/api-keys/:id/revoke | settings.edit permission. Works even after the product lapses. |
Create a key with a name and one or more scopes:
{ "name": "Website orders", "scopes": ["orders:read"] }Scopes are orders:read and menu:read. (orders:write may still appear
on keys made before 10 November 2026; it grants nothing and can no longer
be chosen.) The response includes key, in the form <prefix>.<secret>
(the prefix starts with tk_). It is shown once: the API stores only a
SHA-256 hash of the secret.
Send it as:
Authorization: ApiKey <prefix>.<secret>| Route | Scope |
|---|---|
GET /v1/integration/orders?updatedSince=&cursor=&limit= | orders:read |
GET /v1/integration/orders/:id | orders:read |
GET /v1/integration/menu | menu:read |
A key reads only the restaurant that issued it, up to 10,000 requests an
hour. Errors: 401 for a missing, malformed, unknown or revoked key; 403
api_key_scope_missing; 402 module_not_included; 429 over the limit.
Paging through orders is described in the
webhooks guide.
Sources
- Bearer check and tenant resolution:
apps/api/src/auth/auth.guard.ts - Token signing and default lifetime:
apps/api/src/auth/access-token.ts; session lifetime:apps/api/src/auth/user-session.ts - Auth routes, throttles and origin guard:
apps/api/src/auth/auth.controller.ts,apps/api/src/auth/staff-origin.guard.ts - Sign-in, refresh and error codes:
apps/api/src/auth/auth.service.ts - Self-hosted auth decision:
docs/adr/004-self-hosted-auth.md - Permissions:
apps/api/src/auth/permission.guard.ts,packages/shared-types/src/permissions.ts - API keys:
apps/api/src/modules/api-keys/,packages/shared-types/src/api-keys.ts,apps/api/src/auth/api-key.guard.ts,apps/api/src/auth/api-key-access.guard.ts - Integration API:
apps/api/src/modules/integration-api/integration-api.controller.ts