feat(api-gateway): accept a list of API secrets for verification (#10985)

* feat(api-gateway): accept a list of API secrets for verification

Adds `CUBEJS_API_SECRETS` (comma-separated) as a sibling of
`CUBEJS_API_SECRET`. When set, `CUBEJS_API_SECRETS` takes precedence:
the gateway tries each secret in the list when verifying a JWT and
accepts the token if any of them matches the signature. Signing
behavior is unchanged — callers still sign with whatever single
secret they hold.

This enables zero-downtime rotation of the API secret. During a
rotation window operators can publish the outgoing, current, and
incoming secrets together in `CUBEJS_API_SECRETS`; in-flight tokens
signed by the outgoing secret keep verifying until they expire or
are reissued.

- New optional `apiSecrets: string[]` on `ApiGatewayOptions` and
  `CreateOptions` (server-core).
- `createDefaultCheckAuth` iterates `apiSecrets` when present;
  otherwise falls back to the singular `apiSecret`. An explicit
  `options.key` (used by the playground/system auth path) still
  wins, so playground behavior is unchanged.
- JWK auth is unaffected — when `jwkUrl` is configured the secret
  is fetched dynamically from JWKS, so iterating a static list
  would be meaningless.
- `Cube.apiSecrets()` static accessor mirrors `Cube.apiSecret()`.

Tests cover: accept any listed secret, reject unlisted, list takes
precedence over singular, empty list falls back, playground path
isolated.

* refactor(api-gateway): move multi-secret iteration into default checkAuth

Instead of looping over candidate secrets in the gateway's returned auth
middleware, the default checkAuth implementation now tries each configured
secret internally. The middleware reverts to a single checkAuthFn(auth)
call with one try/catch, matching the original structure.

This keeps the secret-rotation logic where it belongs (the default token
verifier) and avoids invoking the verifier wrapper from an outer loop. JWK
auth resolves its key dynamically by kid, so it remains a single-secret
path. Expiry/nbf failures still short-circuit so the real cause isn't
shadowed by a later "invalid signature".

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

* refactor(api-gateway): read API secrets via env.ts; cover playground+secrets

Addresses code-review feedback:

1. Route env access through `@cubejs-backend/shared` env.ts instead of
   reading process.env directly. Adds `apiSecret` and `apiSecrets`
   accessors (the latter trims, drops empties and deduplicates), and
   switches OptsHandler and CubejsServer.apiSecret()/apiSecrets() to
   getEnv(). Removes the now-redundant apiSecretsEnv helper + its test;
   parsing/dedup coverage moves to env.test.ts.

2. Adds an api-gateway test for CUBEJS_API_SECRETS coexisting with
   playgroundAuthSecret: playground token and any listed secret are
   accepted, while the shadowed singular apiSecret and an unknown secret
   are rejected.

3. Verified consistency with cube-runtime: CloudApiGateway does not
   override createDefaultCheckAuth/createCheckAuthFn (it only overrides
   createCheckAuthSystemFn for a playground-secret list, calling
   createDefaultCheckAuth({ key }) per secret). The options.key-first
   precedence keeps that path single-key, so no override conflict.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: bsod90

docs/content/product/configuration/reference/environment-variables.mdx

@@ -19,6 +19,23 @@ The secret key used to sign and verify JWTs. Generated on project scaffold with
 See also the [`check_auth` configuration
 option](/product/configuration/reference/config#check_auth).
 
+## `CUBEJS_API_SECRETS`
+
+A comma-separated list of secret keys accepted when verifying JWTs. Lets
+operators rotate the API secret without downtime: during a rotation window,
+include the previous, current, and incoming secrets together so in-flight
+tokens signed by any of them continue to verify.
+
+When `CUBEJS_API_SECRETS` is set, it takes precedence over
+[`CUBEJS_API_SECRET`](#cubejs-api-secret) — only the listed secrets are
+accepted. Whitespace around entries is trimmed and duplicates are dropped.
+Tokens are still signed with whichever single secret the issuer holds; this
+variable affects verification only.
+
+| Possible Values                          | Default in Development | Default in Production |
+| ---------------------------------------- | ---------------------- | --------------------- |
+| A comma-separated list of valid strings  | N/A                    | N/A                   |
+
 ## `CUBEJS_APP`
 
 An application ID used to uniquely identify the Cube deployment. Can be

packages/cubejs-api-gateway/src/gateway.ts

@@ -177,6 +177,8 @@ class ApiGateway {
 
   protected readonly playgroundAuthSecret?: string;
 
+  protected readonly apiSecrets?: string[];
+
   // eslint-disable-next-line @typescript-eslint/no-unused-vars
   protected readonly event: (name: string, props?: object) => void;
 
@@ -202,6 +204,9 @@ class ApiGateway {
     this.standalone = options.standalone;
     this.basePath = options.basePath;
     this.playgroundAuthSecret = options.playgroundAuthSecret;
+    this.apiSecrets = options.apiSecrets && options.apiSecrets.length > 0
+      ? options.apiSecrets
+      : undefined;
 
     this.queryRewrite = options.queryRewrite || (async (query) => query);
     this.subscriptionStore = options.subscriptionStore || new LocalSubscriptionStore();
@@ -2456,7 +2461,7 @@ class ApiGateway {
   }
 
   protected createDefaultCheckAuth(options?: JWTOptions, internalOptions?: CheckAuthInternalOptions): PreparedCheckAuthFn {
-    type VerifyTokenFn = (auth: string, secret: string) => Promise<object | string> | object | string;
+    type VerifyTokenFn = (auth: string) => Promise<object | string> | object | string;
 
     const verifyToken = (auth, secret) => jwt.verify(auth, secret, {
       algorithms: <JWTAlgorithm[] | undefined>options?.algorithms,
@@ -2465,7 +2470,44 @@ class ApiGateway {
       subject: options?.subject,
     });
 
-    let checkAuthFn: VerifyTokenFn = verifyToken;
+    // `options.key` wins (used by the playground/system path), then the
+    // rotation list (`CUBEJS_API_SECRETS`), then the singular `apiSecret`.
+    let candidateSecrets: string[];
+    if (options?.key) {
+      candidateSecrets = [options.key];
+    } else if (this.apiSecrets && this.apiSecrets.length > 0) {
+      candidateSecrets = this.apiSecrets;
+    } else if (this.apiSecret) {
+      candidateSecrets = [this.apiSecret];
+    } else {
+      candidateSecrets = [];
+    }
+
+    // Default implementation: accept the token if any configured secret
+    // verifies it. Token-level failures (expiry, nbf) reproduce for every
+    // secret, so surface them immediately rather than shadowing the real
+    // cause with a later "invalid signature".
+    let checkAuthFn: VerifyTokenFn = (auth) => {
+      let lastError: any;
+
+      for (const candidate of candidateSecrets) {
+        try {
+          return verifyToken(auth, candidate);
+        } catch (e: any) {
+          lastError = e;
+          if (e?.name === 'TokenExpiredError' || e?.name === 'NotBeforeError') {
+            throw e;
+          }
+        }
+      }
+
+      if (lastError) {
+        throw lastError;
+      }
+
+      // No secret configured at all — reproduce the upstream JWT error.
+      return verifyToken(auth, undefined);
+    };
 
     if (options?.jwkUrl) {
       const jwks = createJWKsFetcher(options, {
@@ -2519,12 +2561,10 @@ class ApiGateway {
       };
     }
 
-    const secret = options?.key || this.apiSecret;
-
     return async (req, auth) => {
       if (auth) {
         try {
-          req.securityContext = await checkAuthFn(auth, secret);
+          req.securityContext = await checkAuthFn(auth);
           req.signedWithPlaygroundAuthSecret = Boolean(internalOptions?.isPlaygroundCheckAuth);
         } catch (e: any) {
           if (this.enforceSecurityChecks) {

packages/cubejs-api-gateway/src/types/gateway.ts

@@ -70,6 +70,8 @@ interface ApiGatewayOptions {
   subscriptionStore?: any;
   enforceSecurityChecks?: boolean;
   playgroundAuthSecret?: string;
+  /** Rotation window: any listed secret verifies. Takes precedence over `apiSecret`. */
+  apiSecrets?: string[];
   serverCoreVersion?: string;
   contextRejectionMiddleware?: ContextRejectionMiddlewareFn;
   wsContextAcceptor?: ContextAcceptorFn;

packages/cubejs-api-gateway/test/auth.test.ts

@@ -640,6 +640,211 @@ describe('test authorization', () => {
     ]);
   });
 
+  test('apiSecrets - accepts tokens signed by any secret in the list', async () => {
+    const loggerMock = jest.fn(() => {
+      //
+    });
+    const handlerMock = jest.fn((req, res) => {
+      res.status(200).end();
+    });
+
+    const apiSecrets = ['outgoing-secret', 'current-secret', 'incoming-secret'];
+
+    const { app } = createApiGateway(handlerMock, loggerMock, {
+      apiSecrets,
+    });
+
+    for (const secret of apiSecrets) {
+      const token = generateAuthToken({ uid: 5 }, {}, secret);
+      // eslint-disable-next-line no-await-in-loop
+      await request(app)
+        .get('/test-auth-fake')
+        .set('Authorization', `Authorization: ${token}`)
+        .expect(200);
+    }
+
+    expect(handlerMock.mock.calls.length).toEqual(apiSecrets.length);
+  });
+
+  test('apiSecrets - rejects tokens not signed by any secret in the list', async () => {
+    const loggerMock = jest.fn(() => {
+      //
+    });
+    const handlerMock = jest.fn((req, res) => {
+      res.status(200).end();
+    });
+
+    const { app } = createApiGateway(handlerMock, loggerMock, {
+      apiSecrets: ['a', 'b', 'c'],
+    });
+
+    const badToken = generateAuthToken({ uid: 5 }, {}, 'not-in-list');
+
+    await request(app)
+      .get('/test-auth-fake')
+      .set('Authorization', `Authorization: ${badToken}`)
+      .expect(403);
+
+    expect(handlerMock.mock.calls.length).toEqual(0);
+  });
+
+  test('apiSecrets - takes precedence over apiSecret when both are configured', async () => {
+    const loggerMock = jest.fn(() => {
+      //
+    });
+    const handlerMock = jest.fn((req, res) => {
+      res.status(200).end();
+    });
+
+    // Base fixture's apiSecret='secret' must be ignored once apiSecrets is set.
+    const { app } = createApiGateway(handlerMock, loggerMock, {
+      apiSecrets: ['only-this-one'],
+    });
+
+    const oldSingularToken = generateAuthToken({ uid: 5 }, {}, 'secret');
+
+    await request(app)
+      .get('/test-auth-fake')
+      .set('Authorization', `Authorization: ${oldSingularToken}`)
+      .expect(403);
+
+    const listedToken = generateAuthToken({ uid: 5 }, {}, 'only-this-one');
+
+    await request(app)
+      .get('/test-auth-fake')
+      .set('Authorization', `Authorization: ${listedToken}`)
+      .expect(200);
+
+    expect(handlerMock.mock.calls.length).toEqual(1);
+  });
+
+  test('apiSecrets - empty array falls back to singular apiSecret', async () => {
+    const loggerMock = jest.fn(() => {
+      //
+    });
+    const handlerMock = jest.fn((req, res) => {
+      res.status(200).end();
+    });
+
+    const { app } = createApiGateway(handlerMock, loggerMock, {
+      apiSecrets: [],
+    });
+
+    const token = generateAuthToken({ uid: 5 }, {}, 'secret');
+
+    await request(app)
+      .get('/test-auth-fake')
+      .set('Authorization', `Authorization: ${token}`)
+      .expect(200);
+
+    expect(handlerMock.mock.calls.length).toEqual(1);
+  });
+
+  test('apiSecrets - expired token signed by a listed secret is rejected', async () => {
+    const loggerMock = jest.fn(() => {
+      //
+    });
+    const handlerMock = jest.fn((req, res) => {
+      res.status(200).end();
+    });
+
+    const { app } = createApiGateway(handlerMock, loggerMock, {
+      apiSecrets: ['s1', 's2', 's3'],
+    });
+
+    const expiredToken = jwt.sign({ uid: 5 }, 's1', { expiresIn: '-1s' });
+
+    await request(app)
+      .get('/test-auth-fake')
+      .set('Authorization', `Authorization: ${expiredToken}`)
+      .expect(403);
+
+    expect(handlerMock.mock.calls.length).toEqual(0);
+  });
+
+  test('apiSecrets - playground secret path is unaffected', async () => {
+    const loggerMock = jest.fn(() => {
+      //
+    });
+    const handlerMock = jest.fn((req, res) => {
+      res.status(200).end();
+    });
+
+    const playgroundAuthSecret = 'playgroundSecret';
+
+    const { app } = createApiGateway(handlerMock, loggerMock, {
+      apiSecrets: ['outgoing', 'current'],
+      playgroundAuthSecret,
+    });
+
+    const playgroundToken = generateAuthToken({ uid: 5 }, {}, playgroundAuthSecret);
+
+    await request(app)
+      .get('/test-auth-fake')
+      .set('Authorization', `Authorization: ${playgroundToken}`)
+      .expect(200);
+
+    const apiToken = generateAuthToken({ uid: 5 }, {}, 'current');
+
+    await request(app)
+      .get('/test-auth-fake')
+      .set('Authorization', `Authorization: ${apiToken}`)
+      .expect(200);
+
+    expect(handlerMock.mock.calls.length).toEqual(2);
+  });
+
+  test('apiSecrets - coexists with playgroundAuthSecret (both sources active)', async () => {
+    const loggerMock = jest.fn(() => {
+      //
+    });
+    const handlerMock = jest.fn((req, res) => {
+      res.status(200).end();
+    });
+
+    const playgroundAuthSecret = 'playgroundSecret';
+
+    // Base fixture's singular apiSecret='secret' is shadowed by apiSecrets.
+    const { app } = createApiGateway(handlerMock, loggerMock, {
+      apiSecrets: ['outgoing', 'current'],
+      playgroundAuthSecret,
+    });
+
+    // A token signed by the playground secret is accepted via the system path.
+    const playgroundToken = generateAuthToken({ uid: 5 }, {}, playgroundAuthSecret);
+    await request(app)
+      .get('/test-auth-fake')
+      .set('Authorization', `Authorization: ${playgroundToken}`)
+      .expect(200);
+
+    // A token signed by any listed secret is accepted via the main path.
+    for (const secret of ['outgoing', 'current']) {
+      const apiToken = generateAuthToken({ uid: 5 }, {}, secret);
+      // eslint-disable-next-line no-await-in-loop
+      await request(app)
+        .get('/test-auth-fake')
+        .set('Authorization', `Authorization: ${apiToken}`)
+        .expect(200);
+    }
+
+    // The singular apiSecret is shadowed by apiSecrets and is not a playground
+    // secret either, so a token signed with it is rejected by both paths.
+    const shadowedSingularToken = generateAuthToken({ uid: 5 }, {}, 'secret');
+    await request(app)
+      .get('/test-auth-fake')
+      .set('Authorization', `Authorization: ${shadowedSingularToken}`)
+      .expect(403);
+
+    // A token signed by neither the playground secret nor any listed secret.
+    const strangerToken = generateAuthToken({ uid: 5 }, {}, 'not-anywhere');
+    await request(app)
+      .get('/test-auth-fake')
+      .set('Authorization', `Authorization: ${strangerToken}`)
+      .expect(403);
+
+    expect(handlerMock.mock.calls.length).toEqual(3);
+  });
+
   test('coerceForSqlQuery claimsNamespace', async () => {
     const loggerMock = jest.fn(() => {
       //

packages/cubejs-backend-shared/src/env.ts

@@ -1933,6 +1933,20 @@ const variables: Record<string, (...args: any) => any> = {
     .asString(),
   playgroundAuthSecret: () => get('CUBEJS_PLAYGROUND_AUTH_SECRET')
     .asString(),
+  apiSecret: () => get('CUBEJS_API_SECRET')
+    .asString(),
+  // Comma-separated rotation list. Trimmed, empties dropped, deduplicated.
+  // Takes precedence over the singular `apiSecret` when non-empty.
+  apiSecrets: (): string[] | undefined => {
+    const raw = get('CUBEJS_API_SECRETS').asString();
+    if (!raw) {
+      return undefined;
+    }
+    const unique = Array.from(
+      new Set(raw.split(',').map((s) => s.trim()).filter(Boolean))
+    );
+    return unique.length > 0 ? unique : undefined;
+  },
   agentFrameSize: () => get('CUBEJS_AGENT_FRAME_SIZE')
     .default('200')
     .asInt(),

packages/cubejs-backend-shared/test/env.test.ts

@@ -143,3 +143,38 @@ describe('getEnv', () => {
     );
   });
 });
+
+describe('getEnv(apiSecret / apiSecrets)', () => {
+  afterEach(() => {
+    delete process.env.CUBEJS_API_SECRET;
+    delete process.env.CUBEJS_API_SECRETS;
+  });
+
+  test('apiSecret', () => {
+    expect(getEnv('apiSecret')).toBeUndefined();
+
+    process.env.CUBEJS_API_SECRET = 'secret';
+    expect(getEnv('apiSecret')).toBe('secret');
+  });
+
+  test('apiSecrets - unset / empty / blanks resolve to undefined', () => {
+    expect(getEnv('apiSecrets')).toBeUndefined();
+
+    process.env.CUBEJS_API_SECRETS = '';
+    expect(getEnv('apiSecrets')).toBeUndefined();
+
+    process.env.CUBEJS_API_SECRETS = ',  ,,';
+    expect(getEnv('apiSecrets')).toBeUndefined();
+  });
+
+  test('apiSecrets - trims, drops empties, deduplicates, preserves order', () => {
+    process.env.CUBEJS_API_SECRETS = ' a , b , c ';
+    expect(getEnv('apiSecrets')).toEqual(['a', 'b', 'c']);
+
+    process.env.CUBEJS_API_SECRETS = 'a,b,a,c,b';
+    expect(getEnv('apiSecrets')).toEqual(['a', 'b', 'c']);
+
+    process.env.CUBEJS_API_SECRETS = 'only';
+    expect(getEnv('apiSecrets')).toEqual(['only']);
+  });
+});