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
Community SaaS plugin / SDK requests	Basic auth + optional X-License-Token	Authorization: Basic ..., X-License-Token: AXON-..., X-Axonflow-Client: <id>/<v>	per-tenant tier resolution + scope check; see License Matrix Headers below
Orchestrator protected workflow APIs	Basic auth (tenant derived from credentials)	Authorization: Basic ...	tenant ID derived server-side from authenticated client
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_ID
• AXONFLOW_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_id
• user_token

This is why the public docs often talk about both SDK credentials and request identity fields. They are related, but not identical.

License Matrix Headers (X-License-Token + X-Axonflow-Client)

On Community SaaS endpoints (try.getaxonflow.com and self-hosted community-saas overlays), every governed plugin or SDK request can carry two additional headers that drive per-tenant tier resolution and scope validation per ADR-050:

X-Axonflow-Client: <client-id>/<version>

Identifies which plugin or SDK is making the request. Set on every governed request automatically by the AxonFlow plugins (Claude Code, Cursor, Codex, OpenClaw) and SDKs (TypeScript, Python, Go, Java) — you don't set it manually.

Examples that the agent recognises:

Header value	Maps to scope
openclaw/2.1.0	plugin
claude-code-plugin/1.1.0	plugin
cursor-plugin/1.1.0	plugin
codex-plugin/1.1.0	plugin
sdk-typescript/7.8.0	sdk
sdk-python/7.8.0	sdk
sdk-go/7.8.0	sdk
sdk-java/7.8.0	sdk
(header absent)	full (default)

The agent uses the derived scope to validate that any presented X-License-Token is authorised for that scope — a token issued for the SaaS Plugin path can't be used as SaaS SDK auth, and vice versa.

The agent also captures the value into the Community SaaS telemetry table under the client column so operators can see per-plugin / per-SDK request distribution.

X-License-Token: AXON-<base64url-payload>.<base64url-signature>

A Pro-tier license token issued by Stripe Checkout. Optional — absent means Free-tier baseline (3-day audit retention, 200 events/day). When present, the agent validates the signature, the aud claim against the SaaS Plugin path's accept list, the scope against X-Axonflow-Client via HasScope(), and the tenant binding against the Basic-auth-derived tenant.

Validation outcomes:

• Valid token + matching plugin_user_licenses row → Pro tier (30-day retention, 1000 events/day) for the duration of the token (90 days from purchase).
• Token signature invalid → 401 with invalid_license_token reason.
• Token aud not in SaaS Plugin path accept list (e.g. a self-hosted token sent here) → 401 with cross_quadrant_token reason.
• Token aud accepted but scope mismatch (e.g. plugin-aud token + SDK client header) → 401 with scope_mismatch reason.
• Token tenant_id mismatches Basic-auth tenant → 403 with tenant_mismatch reason.
• DB-level revocation (chargeback, dispute) → 401 within ~60 seconds (no caching).

For the full license matrix concept including all six canonical aud values, see License Matrix.

Orchestrator headers

Several Orchestrator surfaces rely on tenant and org headers, especially enterprise and execution-aware routes. Current code paths use headers such as:

• Tenant context (derived from Basic auth credentials)
• X-Org-ID
• X-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:

1. Is this a public runtime call, a portal call, a SCIM call, or an admin call?
2. Does this surface expect Basic auth, bearer token, session cookie, or admin key?
3. Does the request also need tenant or org routing headers?

That sequence is faster than guessing between Authorization, tenant derived from Basic auth, and portal cookies after the fact.

Related Docs

• SDK Authentication
• Agent Endpoints
• Orchestrator Endpoints
• Enterprise Authentication