Sessions & Tokens

Every request to the Platform API is authenticated as a user within a tenant. This page describes exactly how the server turns an incoming request into an identity and a tenant/site scope. For how to obtain a credential in the first place, see Authentication.

Token resolution order

The server checks credentials in a fixed order and uses the first one that resolves:

  1. Authorization: Bearer <JWT> — the JWT is verified directly with AUTH_SECRET (HS256). This is a pure signature check with no database round-trip, which is why it is the right choice for scripts and service-to-service calls.
  2. NextAuth session cookie — __Secure-authjs.session-token. This is the credential a signed-in browser on *.inklura.fr already carries.
# Programmatic: Bearer JWT
curl "https://manage.inklura.fr/api/trpc/auth.getSession" \
  -H "Authorization: Bearer $INKLURA_TOKEN"

The Bearer token and the session cookie are the same HS256 JWT — the cookie is just how a browser stores it. See Authentication → Bearer JWT.

Tenant & site scope

Authentication establishes who you are; a separate step establishes which tenant and site you are acting in.

With a Bearer JWT, the scope is the token. The signed token already carries tenantId and siteId, and the Bearer path reads them straight from the token and returns — it does not consult headers, cookies, or the Host. So a token minted for tenant X always acts as tenant X, whatever host you send it to. This is the mechanism behind the single multi-tenant endpoint at manage.inklura.fr: pick the tenant by picking the token.

For a session-cookie request (a signed-in browser with no explicit scope), the server resolves the scope from, in order:

  1. Headers — X-Tenant-Id and X-Site-Id.
  2. Selection cookies — selected_tenant, selected_site, selected_host.
  3. The request Host — used as a fallback when nothing more explicit is present.
X-Tenant-Id: <tenant uuid>
X-Site-Id:   <site uuid>

The OpenAPI portals advertise these as X-Tenant-ID / X-Site-ID next to the bearerAuth scheme. The tenant/site model itself is described in the Data Model.

Warning

Client-supplied X-Tenant-Id / X-Site-Id are stripped on the shared manage.inklura.fr host as an anti-spoofing measure, so you cannot select a tenant with them there. Carry the tenant in your Bearer token (authoritative on every host), or set the headers only when calling a tenant's own domain.

Dev-only bypass

In development there is a shortcut header:

X-Auth-Bypass: true

When present, the server mints a mock super-admin identity so you can exercise the API without a real login.

Warning

X-Auth-Bypass is a development-only convenience. Never rely on it against manage.inklura.fr — production requests must present a real Bearer JWT or session cookie.

Getting a token

Tip

Once you have a token, set it in the API Explorer's Credentials & context panel to build, copy, and (where enabled) send real requests.

There is no self-serve "create API key" for the full API — because the JWT is signed with the shared AUTH_SECRET, tokens are minted server-side by the platform. Reuse a valid session token, or arrange a service credential. The full walkthrough (session cookie, Bearer JWT, OIDC, magic-link) lives in Authentication.

Feed subsystems are the exception — they use their own scoped FeedApiKey (feed_…) rather than a user session. See Data Model → Feed API keys and the note in Authentication.