Authentication

Theatrical supports two authentication contexts. Most applications use both: an operator API key for transactional API calls, and loyalty member authentication for member-contextual calls (points balance, personal order history, subscription status).

Token-based auth (GAS)

The Global Authentication Service issues JWT operator tokens. These are short-lived and are automatically managed by the SDK’s TokenManager — your application code never handles token rotation.

Configuration

import { TheatricalClient } from '@theatrical/sdk';

const client = TheatricalClient.create({
  apiKey: process.env.THEATRICAL_API_KEY!,  // Your operator API key
  environment: 'production',                // 'sandbox' (default) | 'staging' | 'production'
});

The apiKey is exchanged for a bearer token on first request. Subsequent requests reuse the cached token until five minutes before expiry, at which point the SDK proactively refreshes it. Concurrent requests during a refresh share a single token request — no thundering herd.

Environment variables

.env

THEATRICAL_API_KEY=op_live_xxxxxxxxxx

Caution

Never commit your API key to version control. Use .env files (in .gitignore) and a secrets manager in production.

Token lifecycle

First request
    │
    ▼
GAS token request (apiKey)
    │
    ▼
Bearer token cached in memory (TokenManager)
    │
    ▼  repeated for all requests
HTTP calls with Authorization: Bearer <token>
    │
    ▼  5 minutes before expiry
Proactive token refresh (deduplicated)
    │
    ▼  on 401 response
Token invalidation + one immediate retry

Loyalty member authentication

Member-contextual endpoints take an explicit member ID. A member proves who they are once via loyalty.authenticate; your application then stores the member ID in its own session and passes it to subsequent calls.

Authenticate a member

// After the member submits your login form
const member = await client.loyalty.authenticate(email, password);

// Store the member ID in your own session
req.session.memberId = member.id;

Member-contextual calls

// In an API route or server component
const member = await client.loyalty.getMember(req.session.memberId);
const balance = await client.loyalty.getPointsBalance(member.id);

console.log(`${member.firstName}: ${balance.points} points`);

Note

The SDK never stores member credentials or session state — session management belongs to your application. authenticate returns the full LoyaltyMember; everything after that is keyed by member.id.

Verifying your setup

import { AuthenticationError } from '@theatrical/sdk';

try {
  const sites = await client.sites.list();
  console.log(`Auth OK — ${sites.length} sites accessible`);
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Auth failed:', err.message);
  }
}

Next steps

• Error handling — how AuthenticationError and RateLimitError surface
• Quickstart — make your first authenticated API call