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 and SAML authentication​

Enterprise SSO is tenant-aware and exposes provider-aware SAML endpoints.

Common routes include:

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

The customer portal also exposes SSO configuration endpoints once you are authenticated.

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 and SAML​

Enterprise customers can configure SSO per tenant.

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 SSO rolloutSAML or SSO configuration plus session auth
automated portal administrationportal API keys where appropriate
identity provisioning from Okta or Microsoft Entra IDSCIM 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