{"record":{"id":"51c550d75a9d3332","repo":"mastra-ai/mastra","slug":"workos-api-key-and-client-id-are-required-provide","errorCode":null,"errorMessage":"WorkOS API key and client ID are required. Provide them in the options or set WORKOS_API_KEY and WORKOS_CLIENT_ID environment variables.","messagePattern":"WorkOS API key and client ID are required\\. Provide them in the options or set WORKOS_API_KEY and WORKOS_CLIENT_ID environment variables\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"auth/workos/src/auth-provider.ts","lineNumber":132,"sourceCode":"  protected trustJwtClaims: boolean;\n  protected jwtClaimOptions?: MastraAuthWorkosOptions['jwtClaims'];\n  protected mapJwtPayloadToUser?: MastraAuthWorkosOptions['mapJwtPayloadToUser'];\n  protected membershipCache: LRUCache<string, OrganizationMembership[]>;\n\n  constructor(options?: MastraAuthWorkosOptions) {\n    super({ name: options?.name ?? 'workos' });\n\n    const apiKey = options?.apiKey ?? process.env.WORKOS_API_KEY;\n    const clientId = options?.clientId ?? process.env.WORKOS_CLIENT_ID;\n    // The redirect URI may be resolved later: `init()` derives it from the\n    // host's `publicUrl` when neither the option nor the env var is set.\n    // `getLoginUrl()` fails with a clear error if it never resolves.\n    const redirectUri = options?.redirectUri ?? process.env.WORKOS_REDIRECT_URI ?? '';\n    const cookiePassword =\n      options?.session?.cookiePassword ?? process.env.WORKOS_COOKIE_PASSWORD ?? DEV_COOKIE_PASSWORD;\n\n    if (!apiKey || !clientId) {\n      throw new Error(\n        'WorkOS API key and client ID are required. ' +\n          'Provide them in the options or set WORKOS_API_KEY and WORKOS_CLIENT_ID environment variables.',\n      );\n    }\n\n    if (cookiePassword.length < 32) {\n      throw new Error(\n        'Cookie password must be at least 32 characters. ' +\n          'Set WORKOS_COOKIE_PASSWORD environment variable or provide session.cookiePassword option.',\n      );\n    }\n\n    this.clientId = clientId;\n    this.redirectUri = redirectUri;\n    this.ssoConfig = options?.sso;\n    this.fetchMemberships = options?.fetchMemberships ?? false;\n    this.trustJwtClaims = options?.trustJwtClaims ?? false;\n    this.jwtClaimOptions = options?.jwtClaims;","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/auth/workos/src/auth-provider.ts#L114-L150","documentation":"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.","triggerScenarios":"`new MastraAuthWorkos(options)` where options.apiKey or options.clientId is undefined and the corresponding env vars are unset or empty.","commonSituations":"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.","solutions":["Set both WORKOS_API_KEY and WORKOS_CLIENT_ID in the environment","Pass them explicitly: new MastraAuthWorkos({ apiKey: '...', clientId: '...' })","Check the error occurs before the cookiePassword check — fix this one first, then address any subsequent validation","Verify keys from the WorkOS dashboard (API Keys page) match the environment being deployed to"],"exampleFix":"// before\nconst auth = new MastraAuthWorkos({ redirectUri });\n// after\nconst auth = new MastraAuthWorkos({\n  apiKey: process.env.WORKOS_API_KEY,\n  clientId: process.env.WORKOS_CLIENT_ID,\n  redirectUri,\n});","handlingStrategy":"validation","validationCode":"function assertWorkosConfig(opts) {\n  const apiKey = opts?.apiKey ?? process.env.WORKOS_API_KEY;\n  const clientId = opts?.clientId ?? process.env.WORKOS_CLIENT_ID;\n  const missing = [];\n  if (!apiKey) missing.push('WORKOS_API_KEY');\n  if (!clientId) missing.push('WORKOS_CLIENT_ID');\n  if (missing.length) throw new Error('Missing WorkOS config: ' + missing.join(', '));\n  if (!apiKey.startsWith('sk_')) console.warn('WORKOS_API_KEY usually starts with sk_');\n  return { apiKey, clientId };\n}","typeGuard":"function hasWorkosCredentials(o) {\n  return typeof o === 'object' && o !== null &&\n    typeof o.apiKey === 'string' && o.apiKey.length > 0 &&\n    typeof o.clientId === 'string' && o.clientId.length > 0;\n}","tryCatchPattern":"try {\n  auth = new MastraAuthWorkos(options);\n} catch (e) {\n  if (e.message.includes('WorkOS API key and client ID')) {\n    throw new ConfigError('Set WORKOS_API_KEY and WORKOS_CLIENT_ID before starting the server');\n  }\n  throw e;\n}","preventionTips":["Check both WORKOS_* vars at deployment startup","Sync env between staging and production from one source of truth","Validate key format (sk_ prefix for API keys) in a config test","Construct the auth provider in an init phase so failures surface before traffic"],"tags":["config","env-var","workos","authentication","constructor"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}