Authentication pipelines

A pipeline is a tenant-configured sequence of steps the platform runs during a sign-in (or registration, or token refresh, or password reset). Each step is either a built-in block (validate credentials, challenge MFA, check risk) or a custom Action (your JavaScript code running on the platform, with access to the request context).

If your app needs anything beyond "user types password, gets in", pipelines are how the customisation gets done — on the platform side, not in your app code. Your code just sees the result.

What's a pipeline made of

Three concepts:

Trigger — what kicks off the pipeline. Sign-in, registration, password reset, token refresh, MFA challenge, etc.
Steps — the sequence of operations the pipeline runs. Some are built-in blocks (validate credentials, check policy, issue tokens); some are tenant-authored Actions.
Outputs — what the pipeline produces. Usually a session + tokens, or a structured error.

A typical sign-in pipeline:

1. Validate credentials (built-in)
2. Check risk score (built-in) — abort if > 80
3. Apply pre-auth Action — "if user.org_id is suspended, deny"
4. Challenge MFA if policy requires (built-in)
5. Apply post-auth Action — "log structured event to our SIEM"
6. Issue session + tokens (built-in)

The tenant admin assembles the pipeline in the console. They see a visual builder (drag-and-drop steps + edit Actions); from the runtime's perspective, the pipeline is data the platform executes for every matching trigger.

When you (developer) need to know about pipelines

Most developers don't have to think about pipelines at all. The default pipeline does what you'd expect: validates the user, applies policy, returns a session. Your SDK calls succeed; you don't see the internals.

You'd care about pipelines when:

Your tenant has custom Actions that reject sign-ins based on app-specific rules. Your SDK gets an error code; you handle it.
Your tenant has a custom Action that adds a claim to the access token (e.g., subscription_tier). Your backend reads it from req.user.
You're authoring a custom Action yourself (you're a developer-admin in a small team where the developer also runs the tenant).

The first two are mostly transparent to integrators. The third is a tenant-admin task — pipelines and Actions are configured in the IntelliAuth admin console (Authentication → Flows and Actions) and the authoring guides live in the tenant admin docs.

Pipelines versus webhooks

A frequent question: when is a custom Action the right tool, when is a webhook?

Custom Action — runs synchronously inside the pipeline. Can reject, modify, or annotate the in-flight request. Your code has access to the user, the request context, and platform helpers.
Webhook — fires after the event. Receives the event payload. Can't reject or modify what already happened.

Use Actions for "must happen before sign-in proceeds" — denying sign-ins for suspended orgs, adding claims to tokens. Use webhooks for "let our system know this happened" — logging to a SIEM, kicking off downstream workflows, sending a welcome email from a CRM.

See Webhooks for the webhook concept.

What pipelines unlock

Three patterns that pipelines make easy:

Per-organisation rules without forking the auth code. "If the user belongs to org X, require AAL3" — a 10-line Action, no code change in your app.
Pre-flight checks against external systems. "Before signing in, hit our subscription service — if they're past-due, deny." Pipelines can make outbound HTTP calls (subject to platform safeguards: timeouts, retry limits, allowlists).
Claim enrichment. "Add the user's role, team membership, feature flags to the token so my API doesn't have to look them up." One Action; every downstream API gets the data for free.

What pipelines explicitly aren't:

A replacement for your app's business logic. They run during auth, not during your app's request flow.
A way to bypass the platform's safety rails. Actions run in a sandbox; they can't (for instance) emit raw SQL, talk to the platform's internal services, or skip MFA when policy requires it.
A way to bring your own protocols. Custom OAuth grants, custom token shapes — those would need platform changes, not Actions.

Performance + reliability

Actions run inline in the sign-in path, so they affect sign-in latency directly. The platform enforces:

A per-Action timeout (default 5 seconds; configurable per tenant).
Outbound-call timeouts (default 2 seconds).
A circuit breaker on flaky Actions (if an Action errors > N times, the pipeline falls back to its no-Action behaviour and the audit feed records the breaker trip).

Authors should keep Actions fast (< 100ms typical) and idempotent. If an Action needs to do something slow, it should fire off a webhook to a background worker rather than blocking the sign-in.