feat: Add optional issuer config for access token validation

[m0tzy]

Summary

Adds an opt-in iss claim check to AuthKitCore.verifyToken. When issuer is configured (configure({ issuer }) or WORKOS_ISSUER, resolved by the existing ConfigurationProvider env-var mapping), it is passed to jose.jwtVerify; when unset, behavior is unchanged (no iss check). This flows through to every framework built on authkit-session (tanstack-start, sveltekit, astro).

const issuer = this.config.issuer;
await jwtVerify(token, this.getPublicKey(), 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. A WORKOS_ISSUER value from the value source is split on commas in ConfigurationProvider.convertValueType (trimmed, empties dropped; a single value stays a string); programmatic configure({ issuer }) strings are passed through verbatim.

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

ConfigurationProvider.getConfig() previously only enumerated keys with defaults plus requiredKeys, so an optional key set only in the value source never reached the config handed to AuthKitCore by createAuthService(). It now also enumerates optionalKeys (apiPort, issuer, cookieSameSite, cookieDomain) — this is what makes an env-only WORKOS_ISSUER take effect, and as a side effect fixes the same gap for env-only WORKOS_API_PORT / WORKOS_COOKIE_SAME_SITE / WORKOS_COOKIE_DOMAIN.

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 and workos/authkit-remix#90.

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 JWT issuer validation throughout the shared AuthKit core configuration path.

• Passes configured string or string-array issuers to jose.jwtVerify.
• Resolves WORKOS_ISSUER through full configuration assembly and parses comma-separated environment values.
• Preserves programmatic issuer strings without comma splitting.
• Documents the option and adds focused verification and configuration tests.

Confidence Score: 5/5

The PR appears safe to merge; the changes fully address both previously reported issuer-configuration defects without introducing a new actionable issue.

Environment-only issuers are now included in full configuration assembly, while comma splitting is limited to environment-derived values so programmatic issuer strings remain exact. Both previous threads were manually resolved after these fixes, and no blocking failure remains.

Important Files Changed

Filename	Overview
src/core/config/ConfigurationProvider.ts	Propagates source-only optional configuration and restricts issuer-list parsing to environment values.
src/core/AuthKitCore.ts	Applies the configured issuer constraint when verifying access tokens.
src/core/config/ConfigurationProvider.spec.ts	Covers environment issuer propagation and preservation of comma-containing programmatic issuers.
src/core/AuthKitCore.issuer.spec.ts	Covers unset, scalar, array, and rejected issuer verification behavior.
src/core/config/types.ts	Exposes the optional scalar-or-list issuer configuration type.
README.md	Documents WORKOS_ISSUER, including comma-separated issuer lists and opt-in validation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    A[Programmatic config] --> C[ConfigurationProvider]
    B[WORKOS_ISSUER] --> D[Parse environment-only comma list]
    D --> C
    C --> E[AuthKitCore config]
    E --> F{Issuer configured?}
    F -- No --> G[jwtVerify without issuer constraint]
    F -- Yes --> H[jwtVerify with issuer constraint]

Loading

_{Reviews (2): Last reviewed commit: "Resolve source-only optional keys in get..." | Re-trigger Greptile}