Add optional issuer config for access token validation

[m0tzy]

Summary

Adds an opt-in iss claim check to access token verification via a new issuer config key (configure({ issuer }) or WORKOS_ISSUER, resolved by the existing generic getConfig env-var mapping). When set, it is passed to jose.jwtVerify; when unset, behavior is unchanged (no iss check).

const issuer = getConfig('issuer');
await jwtVerify(accessToken, JWKS, issuer ? { issuer } : undefined);

issuer is string | string[] so an app can accept tokens from more than one issuer (e.g. during an issuer migration); jose's issuer option already accepts both. WORKOS_ISSUER is split on commas in Configuration.getValue (trimmed, empties dropped; a single value stays a string):

configure({ issuer: 'https://api.workos.com/user_management/client_123' });
configure({ issuer: ['https://api.workos.com', 'https://api.workos.com/user_management/client_123'] });
// WORKOS_ISSUER=https://api.workos.com,https://api.workos.com/user_management/client_123

Opt-in rather than defaulted because the API does not mint a single issuer shape — it varies by environment (https://api.workos.com for legacy environments, https://api.workos.com/user_management/<clientId> for environments created since mid-2025, custom auth domains, and flag-gated path variants). Mirrors workos/authkit-nextjs#476.

Link to Devin session: https://app.devin.ai/sessions/0ee38e859a9849658a7cdb2d215d89a6
Open in Devin Desktop: https://app.devin.ai/desktop/session/0ee38e859a9849658a7cdb2d215d89a6?variant=devin
Requested by: @m0tzy

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

---

Original prompt from madison.packer

can we patch this SDK so that the issuer can be either by default (if not passed) or passed a specific issuer?

const issuer = opts.issuer ?? https://${getConfig('apiHostname')}

workos/authkit-react-router#83

[devin-ai-integration]

Devin Review found 1 potential issue.

[greptile-apps]

Greptile Summary

Adds optional access-token issuer validation and extends the follow-up implementation to support multiple accepted issuers.

• Introduces issuer as a programmatic or WORKOS_ISSUER configuration value.
• Parses comma-separated environment values into an accepted-issuer list while preserving programmatic string and array values.
• Passes configured issuer constraints to jose.jwtVerify; issuer validation remains disabled when unset.
• Documents the configuration and adds coverage for absent, single, and multiple issuer values.

Confidence Score: 5/5

The PR appears safe to merge; no outstanding correctness, security, or repository-rule violations were identified.

Issuer values resolve through the existing configuration precedence, multiple values are normalized into the form accepted by JWT verification, and the option is applied only when configured. Both previous findings were resolved after Greptile accepted the implementation-context explanations, and neither remains outstanding.

Important Files Changed

Filename	Overview
src/config.ts	Parses source-provided issuer configuration into a normalized string or list while preserving existing resolution precedence.
src/interfaces.ts	Extends the public configuration contract to accept one or multiple issuers.
src/session.ts	Applies the optional issuer constraint during existing JWT signature and claim verification.
src/config.spec.ts	Covers normalization of single and comma-separated issuer environment values.
src/session.spec.ts	Covers verification behavior with no issuer, one issuer, and multiple issuers.
README.md	Documents the optional issuer setting and comma-separated environment syntax.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[configure or WORKOS_ISSUER] --> B[getConfig issuer]
    B --> C{Configured value}
    C -->|Absent| D[jwtVerify without issuer constraint]
    C -->|Single issuer| E[jwtVerify with issuer string]
    C -->|Comma-separated or array| F[jwtVerify with accepted issuer list]
    D --> G[Access-token verification]
    E --> G
    F --> G

Loading

_{Reviews (2): Last reviewed commit: "Accept a list of issuers via issuer conf..." | Re-trigger Greptile}