docs: clarify custom claims behavior for pre-session interceptors

[ekline]

Summary

The behavior of custom claims returned by the PRE_SESSION_CREATION (pre-session) interceptor is under-documented, which led a developer to believe claim injection was broken when it was actually working as designed. The docs should state the full, current behavior explicitly.

Behavior to document

• No registration required. Custom claims returned in the interceptor response are automatically included in the access token under the custom_claims key. No "custom attribute" dashboard configuration is needed.
• Supported auth methods. The pre-session interceptor fires for all auth methods: passwordless, SSO, OAuth, SAML, and passkeys.
• When it fires. The interceptor runs on every new session creation and on organization switch within an existing session.
• Organization switch. Claims returned during an organization switch are now injected into the access token as well (recently shipped). Document this so developers can rely on org-specific roles and claims being refreshed on switch.
• Persistence. Claims set at session creation persist for the session, so every access token issued for that session includes them.

Proposed work

• Update the auth-flow interceptors page to cover the points above, especially the custom_claims shape and the organization-switch behavior.
• Add a short example showing a decoded access token with custom_claims populated.
• Cover how to add organization-derived claims (for example, the organization name) to the access token via an interceptor, as a self-serve alternative to backend customization.

Source

Surfaced through developer support. No code change is required for the core behavior; this tracks the documentation clarification.

[ekline]

Follow-up: another developer asked, through support, how to add the organization name to the access token claims, and whether an interceptor is the only way. They were unblocked by a backend customization that added org_name to the access token, but the self-serve path is the pre-session interceptor.

This reinforces the scope of this issue: the interceptor docs should explicitly show how to add organization-derived claims (such as org_name) to the access token, and mention when a backend customization is the better fit. Folding this request in here rather than tracking it separately.