API Reference
Authentication

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).

RouteWhat it does
POST /v1/auth/signupCreate an account. Returns needsVerification: true instead of a token when the email must be verified first.
POST /v1/auth/loginEmail and password. 403 email_not_verified until the email is verified, when verification is required.
POST /v1/auth/googleExchange a Google ID token ({ "idToken": "…" }).
POST /v1/auth/refreshNew access token from the tahlib_session cookie. 401 session_expired when the session has ended.
POST /v1/auth/logoutEnd the current session.
GET /v1/auth/meThe signed-in user, their role and permissions at the resolved restaurant.
GET /v1/auth/sessionsThe user's active sessions.
POST /v1/auth/sign-out-allEnd 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):

RouteRequires
GET /v1/api-keyssettings.view permission, Advanced API & Webhooks product (webhooks module)
POST /v1/api-keyssettings.edit permission, webhooks module; 5 per minute
POST /v1/api-keys/:id/revokesettings.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>
RouteScope
GET /v1/integration/orders?updatedSince=&cursor=&limit=orders:read
GET /v1/integration/orders/:idorders:read
GET /v1/integration/menumenu: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