Interface: BackstageClientConfig

@ticketlayer/backstage

@ticketlayer/backstage / BackstageClientConfig

Defined in: client.ts:856

Properties#

accessToken?#

optional accessToken: string | () => string | undefined;

Defined in: client.ts:874

Bearer token (bearer mode). A resolver function is read on every request, so a host that rotates tokens (an embed session refreshed by its parent window) never has to recreate the client.

authMode?#

optional authMode: AuthMode;

Defined in: client.ts:863

Authentication mode:

• 'bearer': Use Authorization header with access/refresh tokens (default)
• 'cookie': Use HTTP-only cookies (for Next.js apps with OAuth)

baseUrl#

baseUrl: string;

Defined in: client.ts:857

credentials?#

optional credentials: RequestCredentials;

Defined in: client.ts:925

The fetch credentials mode. Cookie mode always sends 'include'; bearer mode sends the fetch default unless this says otherwise. The shell's sign-in page sets 'include' on its issuer client so the identity steps can leave the issuer's own login session.

debug?#

optional debug: boolean | DebugConfig;

Defined in: client.ts:868

Enable debug mode for logging all SDK operations. Can be a boolean (enables all logging) or a DebugConfig object for fine-grained control.

dpop?#

optional dpop: DpopSigner;

Defined in: client.ts:918

Sender-constrained tokens (DPoP, RFC 9449), bearer mode only. When set, the access token is sent as Authorization: DPoP <token> with a fresh DPoP proof for each request (and again for a retry), which is how the API accepts a token bound to a key (cnf.jkt). auth.createDpopKey() returns a key that fits.

headers?#

optional headers: Record<string, string>;

Defined in: client.ts:910

onAuthFailure()?#

optional onAuthFailure: () => Promise<boolean>;

Defined in: client.ts:889

Called when a 401 is received. Return true if refresh was successful and the request should be retried. If not provided, default behaviour depends on authMode:

• cookie mode: calls refreshEndpoint automatically
• bearer mode: POSTs refreshToken to refreshEndpoint when both are set; otherwise there is no refresh attempt and the request fails with a SESSION_EXPIRED error

Returns#

Promise<boolean>

onTokenRefresh()?#

optional onTokenRefresh: (accessToken: string, refreshToken: string) => void | Promise<void>;

Defined in: client.ts:880

Called after successful token refresh (bearer mode only). Use this to persist the new tokens.

Parameters#

Returns#

void | Promise<void>

organisationSlug?#

optional organisationSlug: string | () => string | undefined;

Defined in: client.ts:909

Resolves the organisation slug sent as the X-Ticketlayer-Org header in cookie mode. Pass a function so the org can change at runtime (e.g. an org switcher) without recreating the client. If omitted or it returns undefined, the SDK falls back to deriving the org from the subdomain.

refreshEndpoint?#

optional refreshEndpoint: string;

Defined in: client.ts:902

Refresh endpoint. Cookie mode defaults to '/api/oauth/refresh' (the host app's own route). Bearer mode has no default: the API's legacy '/v1/auth/refresh' is gone. A first-party app signed in through the identity issuer uses createAuth(...).createClient(...), which refreshes at the issuer's token endpoint by itself. Otherwise pass one (with refreshToken) or refresh in onAuthFailure; without either, a 401 is not retried and fails with SESSION_EXPIRED. A host that rotates the token behind an accessToken resolver needs neither: the next request reads the new token.

refreshToken?#

optional refreshToken: string;

Defined in: client.ts:875