[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

issuer is added to ConfigurationProvider.optionalKeys (introduced on main by #51) so an env-only WORKOS_ISSUER reaches the config handed to AuthKitCore by createAuthService().

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/743bca3b90094231a7240d01c729566f
Open in Devin Desktop: https://app.devin.ai/desktop/session/743bca3b90094231a7240d01c729566f?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}