fix(org): validate organization_id and report org failures as invalid_token

- Export MissingOrganizationError and OrganizationNotAllowedError from the package root
- Keep invalid_token as the error code for organization failures
- Validate organization_id at construction and normalize it once
- Reject a non-string org_id claim and read it only under the required policy
- Keep the org_id out of the error message and log it instead
- Type organization_policy as Literal["required", "allow"]
- Add tests for the single-string allowlist, no allowlist, allow policy, invalid values and the response header

Author: kishore7snehil

docs/OrganizationPolicy.md

@@ -49,7 +49,7 @@ api_client = ApiClient(ApiClientOptions(
 ))
 ```
 
-`organization_id` compares the opaque `org_id` claim value directly (string comparison, no network call). It does not accept or resolve the human-readable Organization name.
+`organization_id` compares the opaque `org_id` claim value directly (string comparison, no network call). It does not accept or resolve the human-readable Organization name. It must be a non-empty string or a non-empty list of non-empty strings, otherwise `ConfigurationError` is raised at construction.
 
 ## Error Handling
 
@@ -85,7 +85,7 @@ try:
 except MissingOrganizationError as e:
     print(e)            # "Token missing required 'org_id' claim"
     e.get_status_code() # 401
-    e.get_error_code()  # "missing_organization"
+    e.get_error_code()  # "invalid_token"
 ```
 
 ### Organization Not Allowed
@@ -98,10 +98,10 @@ from auth0_api_python import OrganizationNotAllowedError
 try:
     claims = await api_client.verify_access_token(access_token)
 except OrganizationNotAllowedError as e:
-    print(e)            # "Organization 'org_xyz' is not in the allowed list"
+    print(e)            # "Token org_id is not in the allowed list"
     e.get_status_code() # 401
-    e.get_error_code()  # "organization_not_allowed"
+    e.get_error_code()  # "invalid_token"
 ```
 
 > [!NOTE]
-> `MissingOrganizationError` and `OrganizationNotAllowedError` are both subclasses of `VerifyAccessTokenError`. `WWW-Authenticate` response headers (via `get_headers()`) are only populated when the token is verified through `verify_request()`, which wraps these errors before re-raising. Calling `verify_access_token()` directly does not attach response headers.
+> `MissingOrganizationError` and `OrganizationNotAllowedError` are both subclasses of `VerifyAccessTokenError`, so they carry the same `invalid_token` error code and 401 status. The rejected `org_id` is not included in the error message or response headers. It is logged as a warning instead. `WWW-Authenticate` response headers (via `get_headers()`) are only populated when the token is verified through `verify_request()`, which wraps these errors before re-raising. Calling `verify_access_token()` directly does not attach response headers.

src/auth0_api_python/__init__.py

@@ -14,6 +14,8 @@
     ConfigurationError,
     DomainsResolverError,
     GetTokenByExchangeProfileError,
+    MissingOrganizationError,
+    OrganizationNotAllowedError,
 )
 from .types import (
     DomainsResolver,
@@ -34,5 +36,7 @@
     "get_current_actor",
     "get_delegation_chain",
     "InMemoryCache",
+    "MissingOrganizationError",
     "OnBehalfOfTokenResult",
+    "OrganizationNotAllowedError",
 ]

src/auth0_api_python/api_client.py

@@ -1,4 +1,5 @@
 import asyncio
+import logging
 import time
 from collections.abc import Mapping, Sequence
 from typing import Any, Optional, Union
@@ -111,10 +112,23 @@ def __init__(self, options: ApiClientOptions):
             raise ConfigurationError(
                 "organization_policy must be either 'required' or 'allow'"
             )
-        if options.organization_id is not None and options.organization_policy != "required":
+        if options.organization_id is None:
+            self._allowed_org_ids = None
+        elif options.organization_policy != "required":
             raise ConfigurationError(
                 "organization_id is only valid when organization_policy is 'required'"
             )
+        else:
+            org_ids = options.organization_id
+            if isinstance(org_ids, str):
+                org_ids = [org_ids]
+            if not isinstance(org_ids, list) or not org_ids or not all(
+                isinstance(o, str) and o.strip() for o in org_ids
+            ):
+                raise ConfigurationError(
+                    "organization_id must be a non-empty string or a non-empty list of non-empty strings"
+                )
+            self._allowed_org_ids = frozenset(org_ids)
 
         if options.cache_adapter:
             self._discovery_cache = options.cache_adapter
@@ -577,18 +591,13 @@ async def verify_access_token(
                 raise VerifyAccessTokenError(f"Missing required claim: {rc}")
 
         # Organization policy enforcement
-        org_id = claims.get("org_id")
         if self.options.organization_policy == "required":
-            if not org_id:
+            org_id = claims.get("org_id")
+            if not isinstance(org_id, str) or not org_id:
                 raise MissingOrganizationError("Token missing required 'org_id' claim")
-            allowed_orgs = self.options.organization_id
-            if allowed_orgs is not None:
-                if isinstance(allowed_orgs, str):
-                    allowed_orgs = [allowed_orgs]
-                if org_id not in allowed_orgs:
-                    raise OrganizationNotAllowedError(
-                        f"Organization '{org_id}' is not in the allowed list"
-                    )
+            if self._allowed_org_ids is not None and org_id not in self._allowed_org_ids:
+                logging.warning("Rejected token with org_id %r not in the organization_id allowlist", org_id)
+                raise OrganizationNotAllowedError("Token org_id is not in the allowed list")
 
         return claims
 

src/auth0_api_python/config.py

@@ -2,7 +2,7 @@
 Configuration classes and utilities for auth0-api-python.
 """
 
-from typing import TYPE_CHECKING, Callable, Optional, Union
+from typing import TYPE_CHECKING, Callable, Literal, Optional, Union
 
 if TYPE_CHECKING:
     from .cache import CacheAdapter
@@ -36,9 +36,10 @@ class ApiClientOptions:
                               "allow" (default) uses org_id when present but does not require it,
                               matching the pre-existing behavior of verify_access_token.
                               "required" rejects any token without an org_id claim.
-        organization_id: Optional allowlist of org_id claim values (a single value or a list).
-                          Only valid when organization_policy is "required" - passing it with
-                          "allow" raises ConfigurationError at construction time.
+        organization_id: Optional allowlist of org_id claim values (a non-empty string or a non-empty
+                          list of non-empty strings). Only valid when organization_policy is
+                          "required" - passing it with "allow" raises ConfigurationError at
+                          construction time, as does an empty or non-string value.
     """
     def __init__(
             self,
@@ -56,7 +57,7 @@ def __init__(
             client_id: Optional[str] = None,
             client_secret: Optional[str] = None,
             timeout: float = 10.0,
-            organization_policy: str = "allow",
+            organization_policy: Literal["required", "allow"] = "allow",
             organization_id: Optional[Union[str, list[str]]] = None,
     ):
         self.domain = domain

src/auth0_api_python/errors.py

@@ -59,16 +59,10 @@ def get_error_code(self) -> str:
 class MissingOrganizationError(VerifyAccessTokenError):
     """Error raised when organization_policy is 'required' but the token has no org_id claim."""
 
-    def get_error_code(self) -> str:
-        return "missing_organization"
-
 
 class OrganizationNotAllowedError(VerifyAccessTokenError):
     """Error raised when the token's org_id claim is not in the organization_id allowlist."""
 
-    def get_error_code(self) -> str:
-        return "organization_not_allowed"
-
 
 class InvalidAuthSchemeError(BaseAuthError):
     """Error raised when the provided authentication scheme is unsupported."""