docs: Added docs for anonymous sessions - #122
Conversation
|
|
||
| ### 8. Anonymous Sessions | ||
|
|
||
| [Anonymous Sessions](https://auth0.com/docs) give a visitor an Auth0 identity before they log in. The access token issued for an anonymous session is a standard Auth0 Bearer JWT, so `verify_access_token()` and `verify_request()` validate it exactly like any other token. The only difference is the `sub` claim, which starts with `anon@`. |
There was a problem hiding this comment.
This link just points to the docs home page, not the Anonymous Sessions page, so the learn more does not really take the reader anywhere useful. Can we point it to the actual Anonymous Sessions doc page? If the final URL is not ready yet, it may be better to drop the link for now than to ship a placeholder.
There was a problem hiding this comment.
Fixed — updated the link to point to https://auth0.com/docs/manage-users/sessions/anonymous-sessions, which is the canonical Anonymous Sessions docs page.
| - **[Multi-Custom Domain Guide](docs/MultipleCustomDomain.md)** - Configuration modes, resolver patterns, migration, error handling | ||
| - **[Caching Guide](docs/Caching.md)** - Cache tuning, custom adapters (Redis, Memcached) | ||
|
|
||
| ### 8. Anonymous Sessions |
There was a problem hiding this comment.
Tiny naming point. The heading says Anonymous Sessions, but this SDK never creates or stores a session, it only reads the token. The EXAMPLES.md heading calls it Anonymous Callers, which fits an API SDK better. Can we align the two, and maybe add one line saying that session creation lives in the web app SDK, not here?
There was a problem hiding this comment.
Fixed — renamed the section to Anonymous Callers to align with EXAMPLES.md and to reflect that this SDK only validates tokens. Added a sentence clarifying that anonymous session creation is handled by web app.
|
|
||
| Anonymous Sessions give a visitor an Auth0 identity before they log in. The access token issued for an anonymous session is a standard Auth0 Bearer JWT, so this SDK validates it like any other token. The one difference is the `sub` claim, which starts with `anon@`. | ||
|
|
||
| An anonymous token passes verification by default. To treat anonymous callers differently, or block them, check the `sub` claim after verifying the token. The SDK does not make that authorization decision for you. |
There was a problem hiding this comment.
Small clarification here. An anonymous token passes only when it was issued for this API's audience, exactly like any other token, since verify_access_token still checks aud. Can we add half a line saying the anonymous session must be issued for this API's audience? Otherwise a reader may assume every anon@ token will verify here.
There was a problem hiding this comment.
Fixed — replaced "passes verification by default" with two explicit sentences: the token is verified like any other, and it must be issued for this API's audience.
| ### Serve everyone, branch in the handler | ||
|
|
||
| ```python | ||
| import asyncio |
There was a problem hiding this comment.
Two small things on imports. asyncio is imported but not used in this snippet (there is no asyncio.run shown), so it can be dropped. Also the next two snippets use ApiClient and ApiClientOptions without importing them, whereas the other examples in this file repeat their imports. Can we tidy both so each block is copy paste ready?
There was a problem hiding this comment.
Fixed — dropped the unused import asyncio from the first snippet, and added from auth0_api_python import ApiClient, ApiClientOptions to the second and third snippets so all three are copy-paste ready.
| from auth0_api_python import ApiClient, ApiClientOptions | ||
|
|
||
| async def handle_cart(headers): | ||
| api_client = ApiClient(ApiClientOptions( |
There was a problem hiding this comment.
One thing worth flagging for readers. Building the ApiClient inside the handler means the discovery and JWKS caches are recreated on every request, so each call refetches them. This matches the other examples in the file so it is not a blocker, but a one line note to build the client once and reuse it (or pass a shared cache_adapter) would help people who copy this into a hot path.
There was a problem hiding this comment.
Added a note at the end of the section: in production, build ApiClient once at startup and reuse it, or pass a shared cache_adapter, so JWKS and discovery caches persist across requests.
|
|
||
| claims = await api_client.verify_request(headers=headers) | ||
| if claims.get("sub", "").startswith("anon@"): | ||
| raise PermissionError("Anonymous callers are not allowed on this route") |
There was a problem hiding this comment.
For an API this case is usually a 403. PermissionError is fine as pseudo code, but can we add a short note to map it to a 403 in the reader's framework? That makes the intent clearer.
There was a problem hiding this comment.
Added a note: blocking an anonymous caller should return an HTTP 403 Forbidden — replace PermissionError with your framework's error type.
2 participants
Added
documentation for Anonymous Sessions
I have read the Auth0 general contribution guidelines
I have read the Auth0 Code of Conduct
All existing and new tests complete without errors