mastra-ai/mastra · 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

The WorkOS RBAC provider builds its own WorkOS SDK client and therefore needs the same API key and client ID as the auth provider. Resolved from options.apiKey/options.clientId or WORKOS_API_KEY / WORKOS_CLIENT_ID; missing values throw at construction.

Source

Thrown at auth/workos/src/rbac-provider.ts:85

   * Expose roleMapping for middleware access.
   * This allows the authorization middleware to resolve permissions
   * without needing to call the async methods.
   */
  get roleMapping(): RoleMapping {
    return this.options.roleMapping;
  }

  /**
   * Create a new WorkOS RBAC provider.
   *
   * @param options - RBAC configuration options
   */
  constructor(options: MastraRBACWorkosOptions) {
    const apiKey = options.apiKey ?? process.env.WORKOS_API_KEY;
    const clientId = options.clientId ?? process.env.WORKOS_CLIENT_ID;

    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.',
      );
    }

    this.workos = new WorkOS(apiKey, { clientId });
    this.options = options;

    // Initialize LRU cache with configurable size and TTL
    this.rolesCache = new LRUCache<string, Promise<string[]>>({
      max: options.cache?.maxSize ?? DEFAULT_CACHE_MAX_SIZE,
      ttl: options.cache?.ttlMs ?? DEFAULT_CACHE_TTL_MS,
    });
  }

  /**
   * Get all roles for a user from their WorkOS organization memberships.
   *

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 MastraRBACWorkos({ apiKey: '...', clientId: '...' })
3. Reuse the same values as MastraAuthWorkos — both providers need identical credentials
4. Check you instantiated the right class with the right options type (MastraRBACWorkosOptions, not the auth options)

Example fix

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

function assertWorkosRbacConfig(opts) {
  const apiKey = opts?.apiKey ?? process.env.WORKOS_API_KEY;
  const clientId = opts?.clientId ?? process.env.WORKOS_CLIENT_ID;
  if (!apiKey || !clientId) {
    throw new Error('WorkOS RBAC missing credentials: set WORKOS_API_KEY and WORKOS_CLIENT_ID');
  }
  return { apiKey, clientId };
}

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

try {
  rbac = new MastraRBACWorkos(options);
} catch (e) {
  if (e.message.includes('WorkOS API key and client ID')) {
    throw new ConfigError('WorkOS RBAC needs WORKOS_API_KEY and WORKOS_CLIENT_ID (same as auth provider)');
  }
  throw e;
}

When it happens

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

Common situations: RBAC provider added later than the auth provider so env wiring was forgotten; options typed for a different provider (copy-paste from Okta RBAC config); env vars present but scoped to the wrong deployment environment.

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

• WorkOS API key and client ID are required. Provide them in t
• Okta domain is required. Provide it in the options or set OK
• Okta API token is required for RBAC. Provide it in the optio
• 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/5fdf6dbf4bcc5d54. Report an issue: GitHub.