Sessions & Tokens

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

Credential resolution order

The server checks credentials in a fixed order and keeps the first valid one:

  1. Authorization: Bearer <JWT>: the server verifies the JWT signature and expiry. This is the right choice for scripts and service-to-service calls. An invalid or expired Bearer token is ignored, and the server moves on to the next credential.
  2. Session cookie __Secure-authjs.session-token: the credential a browser signed in to the console 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 hold the same JWT: the cookie is just how the browser stores it. Its lifetime depends on how you signed in: 24 hours after a password sign-in. See Authentication.

Tenant & site scope

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

  • Home scope. The token carries your account's tenantId and siteId: your home tenant and site.
  • Several tenants or sites. An account can have access to more than one tenant or site (through memberships). In the console, the active tenant and site are the ones selected in the switcher.
  • Access check. Before any protected procedure runs, the platform checks that your account may act in the requested tenant and site: both must be active, and your account must have access to them (home tenant or membership). If it may not, the call fails with FORBIDDEN ("The requested tenant/site scope is not authorized.").

Request headers do not select the tenant: on the public hosts, the platform sets the scope itself. The tenant/site model is described in the Data Model.

Authentication errors

Code HTTP When
UNAUTHORIZED 401 A protected procedure is called without a valid credential (token missing, invalid or expired). The message depends on the procedure.
FORBIDDEN 403 Your account may not act in the requested tenant or site.
FORBIDDEN 403 The tenant's subscription does not include the procedure's module ("Votre abonnement n'inclut pas ce module (…)").

An expired token has no error of its own: it is ignored, and the call ends in UNAUTHORIZED as if no credential had been sent. A typical response, here for auth.getSession:

{"error":{"json":{"message":"Please log in to access this feature. Your session may have expired.","code":-32001,"data":{"code":"UNAUTHORIZED","httpStatus":401,"path":"auth.getSession","zodError":null}}}}

Getting a token

The quickest way is the Sign in with Inklura button in the API Explorer:

  1. The explorer opens the Inklura console. Sign in the way you usually do: password, invitation link or single sign-on. Any way that opens the console works.
  2. The console shows your account, the active workspace and the token's expiry date, and asks you to authorize the explorer.
  3. You come back to the explorer signed in. The token is filled in, and "Copy cURL" includes it, ready for your terminal.

The token is your console session: it carries your rights until it expires, and cannot be revoked early. The explorer keeps it for the current tab only, unless you tick "Remember the token on this device".

There is no self-serve "create API key" for the full API. For a long-running integration, email support@inklura.fr to arrange a service credential. The full walkthrough (session cookie, Bearer JWT, OIDC, invitation) is in Authentication.

Content feeds are the exception: they use their own scoped FeedApiKey (feed_…) rather than a user session. See the Data Model and Authentication.