Tenant resolution

Every Sessiq account is a tenant, with an ID such as t_demo. Each API request must say which tenant it is for. This page explains how the API works that out, and how subdomains and custom domains fit in.

How the API finds the tenant

The API uses the first of these that is present:

1. The staff or customer token. A signed-in request carries its tenant inside the JWT.
2. The x-tenant-id header.
3. The tenant_id (or tenantId) query parameter.

curl "https://api.example.com/api/v1/availability/sites" \
  -H "x-tenant-id: t_demo"

If none is present, a protected endpoint answers 400 with Missing tenant_id (send x-tenant-id header or tenant_id query param). Public endpoints such as availability still need a tenant to return anything useful, so always send one.

The booking widget and the WordPress and Astro packages send x-tenant-id for you, from the tenantId you configure. See JavaScript widget.

Subdomains and custom domains

Each tenant can have a subdomain (for example demo, giving demo.sessiq.com) and a custom domain (for example booking.example.com). They give the customer booking portal its address.

• Subdomains are lower case. Reserved names such as api, www, admin and app cannot be used.
• A custom domain needs a DNS record that points to Sessiq. The certificate is issued automatically once the domain is set on the tenant.

When you call the API from your own code, always send x-tenant-id, even on a subdomain. Do not rely on the API working out the tenant from a host name.

Set the subdomain or custom domain

The account owner can change both in the admin UI under settings, or with the API:

Method	Path	Description
GET	/api/admin/tenants/subdomain/check	Check whether a subdomain is free. Query: subdomain.
PATCH	/api/admin/tenants/subdomain	Set or clear the subdomain and custom domain.

curl -X PATCH "https://api.example.com/api/admin/tenants/subdomain" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"subdomain": "demo", "customDomain": "booking.example.com"}'

Rules:

• A subdomain is 3–63 characters: lower-case letters, numbers and hyphens, not starting or ending with a hyphen.
• Send null or an empty string to remove a subdomain or custom domain.
• A subdomain or domain already used by another tenant returns 409.
• The change takes effect at once. Links that use the old address stop working.

This endpoint needs the owner role and acts on the tenant in your token.

Local development

Browsers resolve *.localhost to your own machine, so demo.localhost:3000 opens the local portal for the demo tenant (t_demo). No /etc/hosts change is needed. See Setup.

Tenant isolation

The tenant decides which data a request can see. Every query runs inside that tenant's context, and the database enforces the same boundary with row-level security. A token for one tenant cannot read another tenant's data, whatever header it sends. See Architecture.