mastra-ai/mastra · error · Error

WorkOS API key and client ID are required. Provide them in t

Error message

WorkOS API key and client ID are required. Provide them in the options or set WORKOS_API_KEY and WORKOS_CLIENT_ID environment variables.

What it means

MastraAuthWorkos requires both a WorkOS API key and a client ID to build its WorkOS SDK client. They are resolved from options (apiKey, clientId) or WORKOS_API_KEY / WORKOS_CLIENT_ID env vars. Without them no WorkOS API calls are possible, so the constructor throws immediately.

Source

Thrown at auth/workos/src/auth-provider.ts:132

  protected trustJwtClaims: boolean;
  protected jwtClaimOptions?: MastraAuthWorkosOptions['jwtClaims'];
  protected mapJwtPayloadToUser?: MastraAuthWorkosOptions['mapJwtPayloadToUser'];
  protected membershipCache: LRUCache<string, OrganizationMembership[]>;

  constructor(options?: MastraAuthWorkosOptions) {
    super({ name: options?.name ?? 'workos' });

    const apiKey = options?.apiKey ?? process.env.WORKOS_API_KEY;
    const clientId = options?.clientId ?? process.env.WORKOS_CLIENT_ID;
    // The redirect URI may be resolved later: `init()` derives it from the
    // host's `publicUrl` when neither the option nor the env var is set.
    // `getLoginUrl()` fails with a clear error if it never resolves.
    const redirectUri = options?.redirectUri ?? process.env.WORKOS_REDIRECT_URI ?? '';
    const cookiePassword =
      options?.session?.cookiePassword ?? process.env.WORKOS_COOKIE_PASSWORD ?? DEV_COOKIE_PASSWORD;

    if (!apiKey || !clientId) {
      throw new Error(
        'WorkOS API key and client ID are required. ' +
          'Provide them in the options or set WORKOS_API_KEY and WORKOS_CLIENT_ID environment variables.',
      );
    }

    if (cookiePassword.length < 32) {
      throw new Error(
        'Cookie password must be at least 32 characters. ' +
          'Set WORKOS_COOKIE_PASSWORD environment variable or provide session.cookiePassword option.',
      );
    }

    this.clientId = clientId;
    this.redirectUri = redirectUri;
    this.ssoConfig = options?.sso;
    this.fetchMemberships = options?.fetchMemberships ?? false;
    this.trustJwtClaims = options?.trustJwtClaims ?? false;
    this.jwtClaimOptions = options?.jwtClaims;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set both WORKOS_API_KEY and WORKOS_CLIENT_ID in the environment
2. Pass them explicitly: new MastraAuthWorkos({ apiKey: '...', clientId: '...' })
3. Check the error occurs before the cookiePassword check — fix this one first, then address any subsequent validation
4. Verify keys from the WorkOS dashboard (API Keys page) match the environment being deployed to

Example fix

// before
const auth = new MastraAuthWorkos({ redirectUri });
// after
const auth = new MastraAuthWorkos({
  apiKey: process.env.WORKOS_API_KEY,
  clientId: process.env.WORKOS_CLIENT_ID,
  redirectUri,
});

function assertWorkosConfig(opts) {
  const apiKey = opts?.apiKey ?? process.env.WORKOS_API_KEY;
  const clientId = opts?.clientId ?? process.env.WORKOS_CLIENT_ID;
  const missing = [];
  if (!apiKey) missing.push('WORKOS_API_KEY');
  if (!clientId) missing.push('WORKOS_CLIENT_ID');
  if (missing.length) throw new Error('Missing WorkOS config: ' + missing.join(', '));
  if (!apiKey.startsWith('sk_')) console.warn('WORKOS_API_KEY usually starts with sk_');
  return { apiKey, clientId };
}

function hasWorkosCredentials(o) {
  return typeof o === 'object' && o !== null &&
    typeof o.apiKey === 'string' && o.apiKey.length > 0 &&
    typeof o.clientId === 'string' && o.clientId.length > 0;
}

try {
  auth = new MastraAuthWorkos(options);
} catch (e) {
  if (e.message.includes('WorkOS API key and client ID')) {
    throw new ConfigError('Set WORKOS_API_KEY and WORKOS_CLIENT_ID before starting the server');
  }
  throw e;
}

When it happens

Trigger: `new MastraAuthWorkos(options)` where options.apiKey or options.clientId is undefined and the corresponding env vars are unset or empty.

Common situations: New WorkOS project where keys were never added to the deployment; secret manager not wired into the runtime; one of the two vars set but not the other; passing config under a nested key the constructor doesn't read.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

• Okta API token is required for RBAC. Provide it in the optio
• WorkOS API key and client ID are required. Provide them in t
• Okta domain is required. Provide it in the options or set OK
• Supabase URL and anon key are required, please provide them
• WorkOS webhook secret is required. Provide it in options or

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/51c550d75a9d3332. Report an issue: GitHub.