Identity and Access Management
AxonFlow keeps two things apart, and getting them straight is the key to trusting the rest of these docs:
- Machine authentication proves that a service or SDK client may call the runtime. It carries no human user.
- User identity proves who a person is, and there are three distinct planes of it. The old docs blurred these three together, which is why OIDC in particular looked confusing.
Machine authentication (the runtime)
Services and SDK clients authenticate to the Agent gateway with HTTP Basic auth: a clientId and clientSecret pair sent in the Authorization: Basic header. The Agent validates the pair, resolves the tenant context, and forwards the request into the policy pipeline. There is no browser session, no cookie, and no redirect.
This is the right model for backend services, local development, framework integrations (LangChain, LangGraph, CrewAI, and others), and any caller that is a machine rather than a human in a browser. Client credentials are scoped to a single tenant: each pair maps to exactly one clientId, which also serves as the tenant identifier.
The DEPLOYMENT_MODE environment variable sets how strictly credentials are enforced:
| Mode | Auth behavior |
|---|---|
community | Optional. Requests without credentials are accepted with a default tenant context. |
eval | Required. Requests without valid Authorization: Basic credentials receive HTTP 401. |
enterprise | Required. Same enforcement as eval, plus the three user-identity planes below. |
If you are integrating AxonFlow into an application, start with SDK Authentication.
The three planes of user identity
Everything else on this page is user identity, and it splits into three planes that do different jobs. One identity provider (JumpCloud, Okta, Microsoft Entra ID, and others) can drive all three, which is exactly why they get conflated (with one wiring constraint, noted below). Keep them separate:
| Plane | Who or what it identifies | Protocol | What it produces |
|---|---|---|---|
| (a) Portal login | a human signing into the portal UI in a browser | SAML or OIDC | an authenticated portal session (cookie) |
| (b) Fleet / governed-request identity | a tool (for example the Claude Code plugin) acting for a specific developer | OIDC token verification (X-User-Token) | a per-user identity stamped onto a governed API call |
| (c) SCIM provisioning | the user directory itself, and group-to-role mapping | SCIM 2.0 bearer token | provisioned users and role assignments |
(a) Portal login
A person opens the AxonFlow portal in a browser and signs in through your identity provider. AxonFlow supports both protocols for this:
- SAML interactive login works end-to-end for self-hosted (in-vpc) deployments as of v9.15.0.
- OIDC interactive login (browser authorization-code flow) is available as of v9.16.0.
Either way the result is the same: a validated assertion or id_token creates an authenticated portal session. Self-hosted deployments must set SSO_BASE_URL so the assertion or authorization-code callback returns to the deployment's own portal. See Portal Login (SSO) for the protocol flows and SSO Configuration for the setup workflow.
(b) Fleet / governed-request identity
A tool such as the Claude Code plugin calls a governed AxonFlow API on behalf of a specific developer. It carries that developer's identity as a per-user OIDC token in the X-User-Token header, which AxonFlow verifies against the configured issuer, audience, and JWKS. This is token verification only: there is no browser, no redirect, and no login page. Roles resolve from the SCIM-synced directory, never from a claim inside the token. This plane is sometimes called "Path B per-user identity". See Per-Developer Identity and Per-User Token Provisioning.
(c) SCIM provisioning
SCIM keeps the AxonFlow user directory in sync with your identity provider and maps identity-provider groups to AxonFlow roles. It has nothing to do with login: it provisions and de-provisions users and assigns roles on a schedule using a bearer token at /scim/v2. Portal login (plane a) and fleet identity (plane b) both read the roles that SCIM writes. See SCIM 2.0 Provisioning.
How the planes work together
A common enterprise setup uses all three from one identity provider:
- SCIM (plane c) provisions the developer into AxonFlow and assigns their role from an identity-provider group.
- Portal login (plane a), using OIDC here so it can share one configuration with step 3, lets that developer sign into the portal when they need the UI (policy management, approvals, audit review).
- Fleet identity (plane b) stamps that same developer's identity onto governed API calls their tools make, using a per-user OIDC token.
A tenant has a single SSO configuration, and it is either SAML or OIDC. Fleet identity (plane b) requires that configuration to be OIDC. So a tenant that wants both browser portal login and per-user fleet tokens must use OIDC for portal login: one OIDC configuration then drives both (portal login uses the client credentials, the fleet plane uses the audience). SAML portal login and fleet OIDC cannot run on the same tenant. SCIM (plane c) is a separate system and works with either. This is why plane (a) offers a protocol choice while plane (b) is OIDC only.
Machine authentication (Basic auth) runs alongside all of this for service-to-service traffic that carries no human user. The planes are complementary, not alternatives.
Choosing the right approach
| If you need... | Use this |
|---|---|
| Programmatic SDK or API access from a service | Basic auth with clientId/clientSecret (SDK Authentication) |
| Browser portal login for people | Portal Login (SSO) with SAML or OIDC |
| Per-user identity on a tool's governed API calls | Per-Developer Identity with an X-User-Token OIDC token |
| Automated user provisioning and de-provisioning | SCIM 2.0 |
| Identity-provider groups mapped to AxonFlow roles | SCIM group-to-role sync |
| The full enterprise lifecycle | portal login + fleet identity + SCIM together |
Supported protocols and providers
- SAML 2.0 and OIDC both drive portal login (plane a). Named provider presets (Okta, Microsoft Entra ID, and Auth0 for SAML; JumpCloud and generic
oidcfor OIDC) only pre-fill that provider's well-known endpoints; they do not change the protocol contract or the validation path. - OIDC also drives fleet identity (plane b) through per-user token verification.
- SCIM 2.0 (plane c) is implemented per RFC 7643 (Schema) and RFC 7644 (Protocol). The public SCIM guides cover Okta, Microsoft Entra ID, OneLogin, and JumpCloud; other SCIM 2.0 providers integrate through the standard endpoints when they support bearer-token auth and lifecycle sync.
Roles are always resolved from the SCIM group-to-role mapping, the audited directory, never from a role or groups claim inside a login assertion or a fleet token, so an identity-provider claim misconfiguration cannot escalate anyone's access.
