[tusharpandey13]

What

Organization-policy enforcement for @auth0/auth0-api-js. An API can now require or allowlist the caller's organization, enforced only from the verified access token.

Contract

Two client-level options on ApiClientCommonOptions:

organizationPolicy?: 'required' | 'allow'; // default 'allow'
organizationId?: string | string[];        // allowlist; valid only when policy is 'required'

• The constructor rejects organizationId when the policy is not 'required' and throws InvalidConfigurationError.
• Enforcement runs inside verifyAccessToken, against the verified org_id claim only.
• Under 'required': a missing org_id throws MissingOrganizationError; an org_id outside the allowlist throws OrganizationNotAllowedError. A string allowlist is coerced to a one-element list.
• Under 'allow' (the default): no check runs and behavior matches the current release.
• Both errors extend VerifyAccessTokenError (HTTP 401), with codes missing_organization and organization_not_allowed.

Acceptance

• organizationId with a non-'required' policy fails construction
• 'required' plus missing org_id throws MissingOrganizationError (401)
• 'required' plus an org_id outside the allowlist throws OrganizationNotAllowedError (401)
• a string allowlist is coerced to one element
• the 'allow' default leaves behavior unchanged
• vitest (143), build, eslint, and tsc pass

Delivery

Independent PR against main. No dependency on the other Phase-1 PRs, so it is safe to merge first.

Summary by CodeRabbit

• New Features
  • Added configurable organization enforcement for access tokens. Organization membership can remain optional or be required, with an optional allowlist of permitted organization IDs.
  • When enforcement is required, tokens with a missing, blank, or non-matching organization ID are rejected with a specific authentication error.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: b6d9c2e7-6719-4819-954d-97f45a9b28a0

📥 Commits

Reviewing files that changed from the base of the PR and between 7214b36 and 234cc20.

📒 Files selected for processing: 4

• packages/auth0-api-js/src/api-client.ts
• packages/auth0-api-js/src/errors.ts
• packages/auth0-api-js/src/organization-policy.spec.ts
• packages/auth0-api-js/src/types.ts

Included review availability: This review used your included allowance. Your plan provides up to 1 included review per hour; 0 remain after this review.

📝 Walkthrough

ApiClient adds organization policy configuration. The default policy allows tokens without organization claims. The required policy checks the verified org_id claim and, when configured, an organization allowlist. Policy failures use dedicated errors.

Changes: Organization Policy Enforcement

Layer / File(s)	Summary
Organization policy configuration packages/auth0-api-js/src/types.ts, packages/auth0-api-js/src/api-client.ts	ApiClientCommonOptions adds organizationPolicy and organizationId. ApiClient validates these options and copies valid allowlist values at construction.
Verified claim enforcement packages/auth0-api-js/src/api-client.ts, packages/auth0-api-js/src/errors.ts, packages/auth0-api-js/src/organization-policy.spec.ts	After JWT verification, ApiClient checks the org_id claim and optional allowlist. New errors represent missing or disallowed organizations. Tests cover configuration, enforcement, authentication challenges, and allowlist copying.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~20 minutes

Change: Feature

Sequence Diagram(s)

sequenceDiagram
  participant Caller
  participant ApiClient
  participant JWTVerification
  participant OrganizationPolicy
  Caller->>ApiClient: verifyAccessToken(token)
  ApiClient->>JWTVerification: Verify token
  JWTVerification-->>ApiClient: Return verified claims
  ApiClient->>OrganizationPolicy: Check org_id policy
  OrganizationPolicy-->>ApiClient: Return claims or organization error
  ApiClient-->>Caller: Return claims or 401 challenge

Loading

Suggested reviewers: nandan-bhat

Merge Risk: ⚪ Minimal · up to 234cc

No identified organization-policy issue prevents merging after normal checks.

Security architecture risk: 🔵 Low · up to 234cc

The organization check is opt-in and only restricts token acceptance. It uses verified claims, validates configuration, and snapshots the allowlist. No introduced authorization bypass was identified, but downstream adoption and production rollout behavior remain unverified.

Retained concerns
No architecture-level concerns identified.

Security review details

Security Blast Radius

• inferred — The new restriction applies to verification calls sharing an ApiClient instance, across its configured issuers. It is not a per-request resource-ownership check and does not itself establish authorization to a particular tenant’s records or assets.

Trust Boundaries and Controls

• observed — An unverified organization value cannot directly satisfy the new gate: enforcement receives the payload returned by jwtVerify with issuer, audience, algorithm, and required-claim constraints. Organization rejection throws before either successful payload return, and the outer handler preserves the typed authentication failure.

Resilience and Maintainability Implications

• observed — Construction validates organization configuration and copies accepted IDs into a private Set. Enforcement does not reread the caller’s organization options, preventing later array or policy mutation from silently widening this control.

Pre-merge checks: 5

Check name	Status	Explanation
Description Check		Check skipped - CodeRabbit’s high-level summary is enabled.
Title check		The title clearly and concisely identifies the main change: enforcement of the organizationPolicy configuration in auth0-api-js.
Docstring Coverage		No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 4…
Linked Issues check		Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check		Check skipped because no linked issues were found for this pull request.

Full details: Docstring Coverage

Explanation

No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 4 files.

✨ Finishing Touches

📝 Generate docstrings

• Commit to this branch
• Create a new PR

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

_{Comment @coderabbitai help to get the list of available commands.}