Enterprise Portal Operations

The AxonFlow Customer Portal is the enterprise operations surface around the runtime. It lets platform, security, compliance, and engineering teams inspect license status, usage trends, API keys, docs access, exports, deployment mode, and, in In-VPC mode, node visibility.

Use Customer Portal for the operating model. Use this page for the concrete portal surfaces and endpoint behavior that are safe to understand before a protected rollout.

Deployment Config

The portal is deployment-mode aware. Before login, the frontend calls:

GET /api/v1/deployment/config

This endpoint does not require session authentication. It lets the portal decide whether to behave like a tenant-focused SaaS control plane or an infrastructure-aware In-VPC console.

The response includes fields such as:

• mode
• tenant_isolation
• show_node_usage
• show_platform_metrics
• show_deployments

Current defaults:

Deployment mode	tenant_isolation	show_node_usage	show_platform_metrics	show_deployments
saas	true	false	false	false
invpc	false	true	true	true

If DEPLOYMENT_MODE is unset or unknown, the portal defaults to the SaaS configuration. When a portal surface appears missing, check whether deployment config intentionally disabled it.

Usage and Analytics

The portal usage view is backed by:

• GET /api/v1/usage
• GET /api/v1/usage/summary

It helps teams review:

• total API calls
• total LLM requests
• total tokens
• estimated cost
• average latency
• success rate
• event-type breakdowns

In SaaS, usage is organization-scoped. In In-VPC deployments, broader platform-wide queries are guarded by usage:platform_wide.

Governed MCP tool calls — the traffic Claude Code and other MCP clients send through the agent — are recorded as api_call usage events, one per served, authenticated tools/call. That means total API calls and the api_call bucket of the event-type breakdown reflect Claude Code activity, not only direct LLM requests, so the page no longer reads zero when the only traffic is governed tool calls. The cards read GET /api/v1/usage/summary (the summary surface that returns those totals), the read is organization-scoped, and the default window ends today, so current-day traffic is included rather than lagging a day. Usage events are counted per organization and do not carry a per-developer email — for per-developer attribution, use the audit logs or the Claude Code dashboard.

Usage API details

GET /api/v1/usage supports:

Parameter	Values	Notes
start_date	YYYY-MM-DD	Defaults to 30 days before the request
end_date	YYYY-MM-DD	Inclusive by date; backend queries up to the next day
granularity	raw, hourly, daily	Defaults to daily
format	json, csv	Defaults to json
client_id	string	Filters to one client when provided
platform_wide	true	In-VPC only and requires usage:platform_wide

GET /api/v1/usage/summary accepts start_date, end_date, and platform_wide=true, and returns totals for API calls, LLM requests, tokens, cost, latency, success rate, and event types.

CSV output uses different filenames and headers depending on granularity:

Granularity	CSV filename	Header style
raw	usage_events.csv	event ID, event type, instance, HTTP fields, provider/model, tokens, cost, latency, policy counts, created-at
hourly or daily	usage_aggregates.csv	event type, time bucket, event count, tokens, cost, average latency, policy counts, success/error counts

Export Data

The portal exposes recent-window export flows for reporting, investigations, and lightweight operational review:

• GET /api/v1/export/usage
• GET /api/v1/policies/export

Usage export

The usage export writes CSV from usage_events. It is not a full audit-log export; it is built for usage, cost, latency, and provider review.

Current usage export columns:

• timestamp
• client_id
• event_type
• llm_provider
• llm_model
• http_method
• http_path
• http_status_code
• latency_ms
• prompt_tokens
• completion_tokens
• total_tokens
• estimated_cost_cents
• policy_violations

The endpoint accepts start and end as RFC3339 timestamps or YYYY-MM-DD dates. If omitted, it defaults to the most recent 30 days. The legacy days parameter is accepted only when start and end are absent; valid values are 1 through 365. The export is capped at 50,000 rows ordered newest first.

For long-term analytics, treat CSV export as an operational convenience layer rather than the final reporting architecture.

Portal API Keys

Portal API keys are for protected enterprise automation around portal workflows. They are managed through:

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

They are not public runtime client credentials, SCIM bearer tokens, or organization licenses.

The backend stores key prefix, name, scopes, created timestamp, optional expiration, last-used timestamp, and revocation timestamp. The full secret value is only returned once at creation time.

The backend stores a SHA-256 hash of the key, not the full secret. The exposed key_prefix is for recognition and audit review. Nullable timestamps such as expires_at, last_used_at, and revoked_at are omitted when they are not set.

Create request

{
  "name": "billing-analytics-job",
  "scopes": ["read:policies", "write:logs"],
  "expires_in_days": 90
}

If no scopes are supplied, the backend currently defaults to:

• read:policies
• write:logs

DELETE /api/v1/keys/{keyID} marks a key as revoked and returns 204 No Content when successful.

Create and revoke attempts are recorded in the admin audit log as API_KEY_CREATE and API_KEY_REVOKE. Audit details include key ID, name, scopes, and outcome, but never the key value or hash.

License Status

Organization license status is available through:

GET /api/v1/license/status

The current response includes:

• tier
• nodes_total
• nodes_used
• usage_percentage
• status
• expires_at

Available tiers are Developer, Professional, Enterprise, and Plus. Status can surface ACTIVE, EXPIRING_SOON, EXPIRED, or OVER_LIMIT.

Regular portal users can inspect current license state and create or revoke portal API keys. Organization license creation, replacement, and revocation remain admin operations under /api/v1/admin.

Node Management

Node management is deployment-mode specific.

In In-VPC mode, authenticated portal users can access:

• GET /api/v1/nodes
• GET /api/v1/nodes/status

There is also an admin/testing endpoint:

• GET /api/v1/admin/nodes/status?org_id=...

In SaaS mode, node metrics are intentionally unavailable because AxonFlow operates the infrastructure layer. The customer-facing endpoints return 403 with codes such as:

• NODE_METRICS_UNAVAILABLE
• NODE_STATUS_UNAVAILABLE

Active node counting

A node is considered active if it sent a heartbeat within the last 5 minutes. The portal counts recent entries in agent_heartbeats and breaks them down by agent and orchestrator.

Node status is calculated as:

• OK below 80%
• CAUTION at 80% or higher
• WARNING at 90% or higher
• VIOLATION when total active nodes exceed the licensed maximum

Treat node APIs as recent-heartbeat capacity signals, not as a full host-inventory API.

Example status response:

{
  "agents": 6,
  "orchestrators": 2,
  "total": 8,
  "max_allowed": 10,
  "percentage": 80,
  "status": "CAUTION"
}

Example active nodes response:

{
  "total_active": 8,
  "nodes": [
    {
      "instance_id": "agent-a-01",
      "instance_type": "agent",
      "last_seen": "2026-03-30T10:15:00Z"
    }
  ],
  "by_type": {
    "agent": 6,
    "orchestrator": 2
  }
}

The JSON type also includes fields such as hostname, port, and host_info, but those fields are not populated by the current active-node query. Treat the endpoint as capacity and heartbeat visibility.

Docs Access Management

Protected documentation access is managed through:

• GET /api/v1/docs/access
• POST /api/v1/docs/access/grant
• POST /api/v1/docs/access/revoke

These routes use the authenticated customer-portal session. They do not use X-Admin-API-Key or SCIM bearer tokens.

The current implementation integrates with Cloudflare Access group management. The backend requires:

Setting	Purpose
CF_API_TOKEN	Cloudflare API token used by the portal backend
CF_ACCOUNT_ID	Cloudflare account that owns the Access group
CF_ACCESS_GROUP_ID	Access group controlling protected-doc access

If any are missing, the docs-access API returns 503 Service Unavailable with "Documentation access management is not configured".

List response:

{
  "users": ["[email protected]"],
  "total": 1
}

Grant request:

{
  "email": "[email protected]",
  "reason": "security review"
}

The reason field is optional and used for operational logging. An already-present email is treated as a successful no-op.

Grant response:

{
  "success": true,
  "message": "Access granted to [email protected]. They will receive a one-time PIN via email when visiting the protected documentation.",
  "email": "[email protected]"
}

Revoke request:

{
  "email": "[email protected]"
}

Revoke response:

{
  "success": true,
  "message": "Access revoked for [email protected]",
  "email": "[email protected]"
}

Good Portal Workflow

A realistic portal workflow usually looks like this:

1. confirm session and deployment mode
2. inspect license and usage health
3. review connector or provider state
4. check deployment or node status if operating In-VPC
5. export usage or policy data when investigations need a portable artifact
6. grant or revoke protected-doc access as people join or leave the rollout

The portal is not just a dashboard. It is the enterprise operational control surface around the runtime.

Related Docs

• Customer Portal
• Enterprise Authentication
• Organizations, Tenants, and Licenses
• Execution Operations Playbook
• Monitoring Overview