mastra-ai/mastra · error · Error

Okta API token is required for RBAC. Provide it in the optio

Error message

Okta API token is required for RBAC. Provide it in the options or set OKTA_API_TOKEN environment variable.

What it means

The Okta RBAC provider needs an API token to authenticate requests against the Okta API. The constructor resolves it from options.apiToken, falling back to OKTA_API_TOKEN. Without it no client can be authenticated, so construction fails immediately.

Source

Thrown at auth/okta/src/rbac-provider.ts:101

  }

  /**
   * Create a new Okta RBAC provider.
   *
   * @param options - RBAC configuration options
   */
  constructor(options: MastraRBACOktaOptions) {
    const domain = options.domain ?? process.env.OKTA_DOMAIN;
    const apiToken = options.apiToken ?? process.env.OKTA_API_TOKEN;

    if (!domain) {
      throw new Error(
        'Okta domain is required. ' + 'Provide it in the options or set OKTA_DOMAIN environment variable.',
      );
    }

    if (!apiToken) {
      throw new Error(
        'Okta API token is required for RBAC. ' +
          'Provide it in the options or set OKTA_API_TOKEN environment variable.',
      );
    }

    this.oktaClient = new Client({
      orgUrl: `https://${domain}`,
      token: apiToken,
    });

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

View on GitHub (pinned to 75dd419e61)

Solutions

1. Create an Okta API token in the Okta admin console and set OKTA_API_TOKEN
2. Pass it explicitly: new MastraRBACOkta({ domain, apiToken: 'your-token' })
3. Verify secret injection (CI/CD secrets, k8s secrets, .env loading) includes OKTA_API_TOKEN

Example fix

// before
const rbac = new MastraRBACOkta({ domain });
// after
const rbac = new MastraRBACOkta({ domain, apiToken: process.env.OKTA_API_TOKEN });

function assertOktaToken(opts) {
  const token = opts?.apiToken ?? process.env.OKTA_API_TOKEN;
  if (!token || token.length < 10) throw new Error('OKTA_API_TOKEN missing or too short');
  return token;
}

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

try {
  rbac = new MastraRBACOkta(options);
} catch (e) {
  if (e.message.includes('OKTA_API_TOKEN')) {
    console.error('Provide Okta API token via options.apiToken or OKTA_API_TOKEN env');
    process.exit(1);
  }
  throw e;
}

When it happens

Trigger: Calling `new MastraRBACOkta(options)` where options.apiToken is undefined and process.env.OKTA_API_TOKEN is unset/empty (note: this check happens after the domain check, so a missing domain masks it).

Common situations: API token never provisioned in the Okta admin console; secret not injected into the deployment environment; typo like OKTA_APITOKEN.

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 domain is required. Provide it in the options or set OK
• 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 client ID is required. Provide it in the options or set
• Supabase URL and anon key are required, please provide them

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