Auth And Header Matrix
AxonFlow exposes several API surfaces, and they do not all authenticate the same way. This page is the reference for which credential or header model belongs to which surface.
That matters because many integration failures are not business-logic bugs. They are simply the wrong auth model applied to the wrong endpoint family.
Quick Matrix
| Surface | Primary auth model | Important headers or fields | Notes |
|---|---|---|---|
Agent request path (/api/request) | SDK client credentials or direct request fields | client_id, user_token, optional Basic auth in SDK-driven flows | most application traffic starts here |
| Gateway and proxy SDK flows | Basic auth with clientId:clientSecret | Authorization: Basic ... | client secret is optional in community mode, required in enterprise-style deployments |
| Orchestrator protected workflow APIs | Basic auth plus tenant routing | Authorization, X-Tenant-ID, sometimes X-Org-ID and X-User-ID | common for workflow, audit, and execution APIs |
| MCP standalone policy checks | same application auth context as the calling runtime | request body plus normal client context | used when external orchestrators want policy-only checks |
| Customer portal APIs | session auth | axonflow_session cookie | used for most protected portal workflows |
| SCIM provisioning | bearer token | Authorization: Bearer ... | separate from portal session auth |
| Admin organization APIs | admin API key | X-Admin-API-Key | required in SaaS production, optional in some other deployments |
Public Runtime Patterns
SDK and application traffic
The public SDK guidance is centered on client credentials:
AXONFLOW_CLIENT_IDAXONFLOW_CLIENT_SECRET
The SDKs use Basic auth with:
Authorization: Basic base64(clientId:clientSecret)
At the request level, the runtime also uses fields such as:
client_iduser_token
This is why the public docs often talk about both SDK credentials and request identity fields. They are related, but not identical.
Orchestrator headers
Several Orchestrator surfaces rely on tenant and org headers, especially enterprise and execution-aware routes. Current code paths use headers such as:
X-Tenant-IDX-Org-IDX-User-ID
For example, unified execution and audit-adjacent handlers rely on tenant context directly.
Protected Portal Patterns
Session-backed portal APIs
The customer portal uses login and session flows under /api/v1/auth/..., and successful login establishes the axonflow_session cookie. That cookie-backed session is then used for:
- usage and analytics
- API keys
- connectors and providers
- approvals
- exports
- SSO settings
SCIM
SCIM is its own auth model. The portal manages SCIM tokens, but actual provisioning requests use bearer-token auth against /scim/v2/....
Admin APIs
The admin organization surface uses:
- header:
X-Admin-API-Key - env var on the service side:
ADMIN_API_KEY
In the current middleware, SaaS production requires it. Other deployment modes are looser, but that should be treated as an operational choice, not as a reason to blur the auth model in client code.
Practical Advice
When an AxonFlow call fails, identify the endpoint family before changing credentials. A good debugging sequence is:
- Is this a public runtime call, a portal call, a SCIM call, or an admin call?
- Does this surface expect Basic auth, bearer token, session cookie, or admin key?
- Does the request also need tenant or org routing headers?
That sequence is faster than guessing between Authorization, X-Tenant-ID, and portal cookies after the fact.
