Block reference — Session & OAuth

Session blocks decide what the platform hands back to the user after every other check has passed. Issue Session closes a Login or Registration flow with a signed session JWT. Issue Tokens is its OAuth2 counterpart, minting an access token and refresh token for machine-to-machine and browser PKCE flows. The social pair — Social IdP Redirect and Social IdP Callback — bookend the external round-trip to Google, Microsoft, or any other OIDC provider. Revoke Session and Hydra Logout tear sessions back down on logout or a security event. Finalize marks the Flow as intentionally complete when no other terminal block is appropriate.

Most flows you build will touch exactly one block in this family — the terminal — and it will be Issue Session. The rest exist for edge cases: federated sign-in, token refresh, logout choreography, and the occasional non-session flow that still needs a clean terminal state.

The `session.*` namespace

Only Session blocks write to session.*. No other block family touches these fields. The fields written depend on which block ran:

Field	Written by	Transient?
`session.id`	Issue Session	no
`session.aal`	Issue Session	no
`session.issued_at`	Issue Session	no
`session.expires_at`	Issue Session	no
`session.expires_in`	Issue Session	no
`session.factors`	Issue Session	no
`session.raw_token`	Issue Session	yes
`session.access_token`	Issue Session, Issue Tokens	yes
`session.refresh_token`	Issue Session, Issue Tokens	yes

Fields marked transient appear in the immediate /submit response once and are then stripped from the stage-token serialisation. Your application must capture session.raw_token, session.access_token, and session.refresh_token from the final response. You cannot reference them in a later stage — they will not be there.

Picking a block

"Mint a session for a verified user" → Issue Session
"Mint access + refresh tokens (typically OAuth2)" → Issue Tokens
"End a specific session (logout, security event)" → Revoke Session
"Redirect to a social IdP (Google, Microsoft, etc.)" → Social IdP Redirect
"Handle the social IdP's authorization-code callback" → Social IdP Callback
"Terminate every active session in Hydra for this user" → Hydra Logout
"Mark the Flow as intentionally complete (rare; usually a terminal block does this)" → Finalize

Issue Session

Block id: issue_session · Available in: login, registration, password_recovery

The standard happy-path terminal. Issue Session calls the session manager to mint an Aegis-signed session JWT for the verified user and then stops the Flow. Every login, registration, and password-recovery Flow that succeeds should end here. It is the single most-used block in the platform.

Before this block runs, the flow must have resolved a user_id — typically from a Look Up Identity block — and populated event.authentication.methods with the factors the user completed. Issue Session reads both, mints the JWT, and writes the session fields to state.

Reads from state

user_id — the verified user to issue a session for
event.authentication.methods — the authentication methods the user completed in this flow

Writes to state

session.id — unique identifier of the issued session
session.aal — Authentication Assurance Level: aal1 (password only) or aal2 (password + second factor)
session.issued_at — ISO 8601 timestamp when the session was created
session.expires_at — ISO 8601 timestamp after which the session token is invalid
session.expires_in — lifetime of the session in seconds from issuance
session.factors — list of authentication factors that contributed to this session
session.raw_token — signed session JWT (transient — available in this response only)
session.access_token — short-lived OAuth2 access token (transient — available in this response only)
session.refresh_token — long-lived OAuth2 refresh token (transient — available in this response only)

Use when — at the terminal position of any Login, Registration, or Password Recovery flow. It is almost always the last block in the flow's happy-path branch.

Cautions — session.raw_token, session.access_token, and session.refresh_token are transient. Your frontend SDK receives them in the final response and must store them immediately. They cannot be referenced by downstream blocks because the stage-token serialiser strips them before persisting.

Issue Tokens

Block id: issue_tokens · Available in: login, token_refresh (and any flow type — no AllowedTriggers restriction)

Mint an OAuth2 access token and refresh token pair via Hydra. Where Issue Session produces a session JWT oriented around a user's browser session, Issue Tokens produces the short-lived access token and long-lived refresh token that OAuth2 clients exchange for API access. Use this block at the terminal position of M2M flows and flows that drive PKCE code exchange.

Both tokens are written as transient fields. Configure access_token_ttl_seconds and refresh_token_ttl_seconds in the block's settings; sensible defaults are applied if you leave them blank.

Reads from state

user_id — the authenticated user
factors_verified — the factor types the user has proven in this flow
client_id — the OAuth2 client requesting tokens

Writes to state

session.access_token — short-lived access token (transient — available in this response only)
session.refresh_token — long-lived refresh token (transient — available in this response only)
step.<slug>.access_token_expires_in — access token lifetime in seconds
step.<slug>.refresh_token_expires_in — refresh token lifetime in seconds

Use when — OAuth2 / PKCE flows, M2M credential flows, or the dedicated Token Refresh flow where Validate Refresh Token runs first and then this block re-mints the pair.

Revoke Session

Block id: session_revoke · Available in: login, mfa_step_up

End a specific session by its ID. The default revocation reason is self_remove, which is appropriate for user-initiated logout. You can override revoke_reason in the block config to other values — for example security_event when an admin terminates a session on behalf of a user.

For a complete logout that also tears down SSO state in Hydra, place a Hydra Logout block after this one. Revoke Session ends the local session record; Hydra Logout severs the SSO session, preventing the user from silently re-authenticating into applications that trust the same Hydra instance.

Reads from state

session_id — the ID of the session to revoke

Writes to state

step.<slug>.revoked — true when the session was successfully terminated

Use when — a logout flow, or any point in a security-event flow where you need to end a session immediately.

Cautions — There is no undo for a revoked session. The block's IsTerminal flag is set, so the flow engine stops after it runs. Do not place blocks after Revoke Session expecting them to execute.

Block id: social_oidc_redirect · Available in: any system flow trigger (pre-auth phase)

Redirect the browser to a social identity provider's authorization endpoint — Google, Microsoft, GitHub, Apple, or any other OIDC-compatible provider you have configured under Connections. The block generates a redirect URL with a CSRF-proof state value and writes both to state so the callback half of the pattern can verify them.

This block ends the first Flow invocation. The browser leaves IntelliAuth, navigates to the social IdP, and returns to your tenant's callback URL with an authorization code. That callback triggers a new Flow invocation where Social IdP Callback takes over.

Reads from state

social_provider — the connection identifier for the social IdP to redirect to

Writes to state

step.<slug>.redirect_url — the authorization URL the browser should be redirected to
step.<slug>.oidc_request_state — the CSRF-proof state value included in the authorize URL; verified on callback

Use when — the first block in a social login branch, before the user leaves your tenant's login page. Use a Decision block to route to this block when the user clicks a social sign-in button.

Block id: social_oidc_callback · Available in: any system flow trigger (post-auth phase)

Handle the social IdP's authorization-code callback. The block receives the code and state query parameters, verifies the state against what Social IdP Redirect stored, exchanges the code for an id_token, and pins the OIDC-derived identifier to state so a Look Up Identity or Create Identity block can run next.

This block runs in a separate Flow invocation from Social IdP Redirect — the one triggered by the callback URL hit. The two halves do not share a stage token directly; state continuity depends on the platform's OIDC session bridge, which persists the state value between the two invocations.

Reads from state

oidc_code — the authorization code returned by the IdP
oidc_state — the state parameter returned by the IdP (verified against the stored state)

Writes to state

step.<slug>.oidc_callback_processed — true when the code was exchanged and the OIDC identity was pinned to state

Use when — as the first block in the callback Flow invocation of a social login flow, immediately before Look Up Identity or Create Identity.

Hydra Logout

Block id: hydra_logout · Available in: login, mfa_step_up

Terminate every Hydra-side login session for the user, severing SSO connections to every application that authenticated via this tenant's Hydra instance. This is the SSO-aware counterpart to Revoke Session. A complete logout sequence runs Revoke Session first (to end the local session record) and then Hydra Logout (to invalidate SSO state).

The block writes two flags: hydra_logout_dispatched confirms the instruction was sent; hydra_logout_pending reflects that Hydra may still be processing the revocation asynchronously.

Reads from state

user_id — the user whose SSO sessions to terminate

Writes to state

step.<slug>.hydra_logout_dispatched — true when the Hydra adapter received the logout instruction
step.<slug>.hydra_logout_pending — true while Hydra is still processing the revocation

Use when — at the end of a logout flow that needs to clear all SSO sessions, not just the current session token. Always pair with Revoke Session upstream.

Finalize

Block id: finalize · Available in: any flow type (all triggers, all phases)

Mark the Flow as intentionally complete without minting a session or revoking anything. The audit and trace layers read the finalized flag to distinguish a Flow that reached a deliberate end from one that ran out of nodes without a terminal block — which is an authoring error.

Most flows do not need this block explicitly, because Issue Session, Revoke Session, and Hydra Logout all set the terminal flag themselves. Finalize is useful in rare flows that are complete by design but produce no session artifact: a Flow that logs an event and deliberately ends with no further action, or a custom flow where all branches converge on a clean stop.

Reads from state

(no declared inputs)

Writes to state

step.<slug>.finalized — true when the Flow reached this block intentionally
step.<slug>.finalized_at — ISO 8601 timestamp of finalization

Use when — the terminal position of a custom flow that produces no session or token, or as a sentinel at the end of every branch in a branching flow to guarantee the engine always has an explicit stop.

Social login spans two separate Flow invocations, which confuses people the first time they see it. Here is the full sequence:

Flow invocation 1 (triggered by "sign in with Google" click)
  1. Social IdP Redirect       — builds the authorize URL, writes oidc_request_state
  [browser redirects to Google; user authorises]

Flow invocation 2 (triggered by callback URL hit)
  2. Social IdP Callback       — exchanges code for id_token, pins OIDC identifier to state
  3. Look Up Identity          — resolves the OIDC identifier to an existing user (or not)
  4a. (existing user)  →  Issue Session
  4b. (new user)       →  Create Identity → Issue Session

The two invocations do not share a stage token. The platform's OIDC session bridge persists the oidc_request_state written in step 1 and makes it available to the callback verification in step 2. Your flow configuration for the callback URL route should point to a flow that starts at Social IdP Callback, not at Social IdP Redirect.

If you want to handle the "new user" branch differently from the "returning user" branch — for example, requiring an explicit consent screen before account creation — add a Decision block after step 3 that routes on step.<your-lookup-slug>.found.

Block reference — Session & OAuth

The session.* namespace

Picking a block

Issue Session

Issue Tokens

Revoke Session

Social IdP Redirect

Social IdP Callback

Hydra Logout

Finalize

The social sign-in pattern

The `session.*` namespace