Skip to main content

Enterprise Authentication Surfaces

AxonFlow Enterprise uses more than one authentication model because the platform exposes more than one kind of surface.

The most common source of confusion is assuming that all enterprise APIs use the same header or credential pattern. They do not.

The Main Authentication Surfaces​

1. Customer portal session authentication​

This is the standard login flow for the customer portal and many portal-backed enterprise APIs.

Core endpoints:

  • POST /api/v1/auth/login
  • POST /api/v1/auth/logout
  • GET /api/v1/auth/session
  • GET /api/v1/auth/sso/availability

Successful login creates the axonflow_session cookie. Portal-backed APIs then use that session context. Current portal sessions use SameSite=Lax.

The login endpoint is rate-limited to 5 attempts per minute per IP address.

Password reset and change endpoints:

  • POST /api/v1/auth/forgot-password
  • POST /api/v1/auth/reset-password
  • POST /api/v1/auth/change-password

This is also the model used by the current SDK portal-login helpers.

2. SSO portal login (SAML and OIDC)​

Enterprise portal login (plane a of the three identity planes) is tenant-aware and exposes provider-aware routes for both protocols.

SAML routes:

  • GET /auth/saml/{tenantID}/metadata
  • GET /auth/saml/{tenantID}/login
  • POST /auth/saml/{tenantID}/callback

OIDC routes (v9.16.0):

  • GET /auth/oidc/{tenantID}/login
  • GET /auth/oidc/{tenantID}/callback

The pre-login availability check (GET /api/v1/auth/sso/availability) returns the correct login URL for whichever protocol the tenant configured, so a client does not need to know the protocol in advance.

The customer portal also exposes SSO configuration endpoints once you are authenticated. Both SAML and OIDC portal-login providers are configured through the same /api/v1/sso/config surface. The SAML metadata-fetch and provider-default helpers are SAML-specific; OIDC providers are configured from their issuer, audience, JWKS URI, and client credentials. This is portal login only; per-user fleet OIDC tokens (X-User-Token) are a separate plane, covered in Per-Developer Identity.

3. Portal API keys​

Portal API keys are managed through authenticated portal APIs and are useful for automation around the customer portal surface.

Key-management endpoints:

  • GET /api/v1/keys
  • POST /api/v1/keys
  • GET /api/v1/keys/{keyID}
  • DELETE /api/v1/keys/{keyID}

These are not the same thing as SCIM tokens or the public runtime's client credentials.

4. SCIM bearer-token authentication​

SCIM provisioning is its own integration surface:

  • base path: /scim/v2
  • guarded by SCIM-specific bearer-token auth

SCIM discovery endpoints exist within the same surface:

  • /scim/v2/ServiceProviderConfig
  • /scim/v2/Schemas
  • /scim/v2/ResourceTypes

And the core provisioning resources are:

  • /scim/v2/Users
  • /scim/v2/Groups

Treat SCIM as a dedicated provisioning API, not as a generic extension of portal session auth.

Portal Login Flow​

For standard customer-portal access:

  1. the user submits org_id and password to POST /api/v1/auth/login
  2. the portal validates the organization and password
  3. the backend creates a session record
  4. the response sets the axonflow_session cookie
  5. authenticated portal APIs use the session context on subsequent requests

The portal also supports a session-check route:

GET /api/v1/auth/session

That is the easiest way to verify whether the portal session is still active.

SSO configuration (SAML and OIDC)​

Enterprise customers can configure portal SSO per tenant, using SAML or OIDC.

Useful portal-authenticated SSO configuration endpoints include:

  • GET /api/v1/sso/config
  • POST /api/v1/sso/config
  • PUT /api/v1/sso/config
  • PATCH /api/v1/sso/config
  • DELETE /api/v1/sso/config
  • POST /api/v1/sso/config/test
  • GET /api/v1/sso/audit
  • GET /api/v1/sso/providers
  • GET /api/v1/sso/providers/defaults
  • GET /api/v1/sso/sp-metadata
  • POST /api/v1/sso/fetch-metadata

The pre-login availability check is:

GET /api/v1/auth/sso/availability?org_id=YOUR_ORG_ID

This lets a portal client decide whether to present password auth, SSO, or both.

SCIM Token Management​

SCIM token management is handled from the authenticated portal side, while the SCIM provisioning requests themselves use SCIM bearer-token auth.

Token-management endpoints:

  • GET /api/v1/scim/tokens
  • POST /api/v1/scim/tokens
  • DELETE /api/v1/scim/tokens/{tokenID}

This separation is worth understanding operationally:

  • portal admins create and manage SCIM tokens through the authenticated portal
  • the identity provider uses those tokens against /scim/v2/...

Admin Organization APIs​

The organization-admin APIs are a separate admin surface under:

/api/v1/admin

These routes are guarded by admin-specific middleware rather than the ordinary customer-portal session model.

Examples include:

  • GET/POST /api/v1/admin/organizations
  • GET/PATCH/DELETE /api/v1/admin/organizations/{org_id}
  • POST /api/v1/admin/organizations/{org_id}/password
  • GET/POST/DELETE /api/v1/admin/organizations/{org_id}/license

This is one of the clearest examples of why "all enterprise APIs use the same auth" is the wrong mental model.

SDK Portal Authentication​

The current SDKs support portal login helpers that target the standard login endpoint and store the session cookie client-side.

The underlying behavior is aligned across SDKs:

  • login via POST /api/v1/auth/login
  • store the session cookie
  • use that cookie for portal-backed requests
  • clear it on logout

That means SDK-driven portal operations are using the same real authentication model as browser portal usage, not a separate fake or simplified API.

When to Use Which Authentication Method​

Use caseRecommended auth model
human user using the portalsession auth
browser-based enterprise UI workflowssession auth
organization portal SSO rolloutSAML or OIDC portal login plus session auth
per-user identity on a tool's governed API callsX-User-Token OIDC token (fleet identity)
automated portal administrationportal API keys where appropriate
identity provisioning from Okta, Microsoft Entra ID, OneLogin, or another SCIM IdPSCIM bearer tokens
admin org lifecycle operationsadmin-gated /api/v1/admin APIs

Common Mistakes​

  • treating SCIM as if it used the same auth model as the portal
  • assuming all enterprise endpoints accept the same org headers or bearer token
  • forgetting that portal login establishes a cookie-backed session
  • debugging SSO failures as if they were password-login failures
  • using portal API keys where a SCIM token is actually required
Last updated on