POST /v1/execute, which checks one stage and returns a decision without calling a model, and the hook endpoints of coding agents (Claude Code, Codex, Cursor).
Request flow
Before any plugin runs, the router prepares the request in this order: it validates the agent ID, checks the path and method, sets the internalX-Xenovia-Agent-Path, and authenticates the key. Only an authenticated request has its body read and checked (size, JSON, content modality). Then the router resolves the agent’s provider, rewriting the request’s model to the provider’s configured model, and the plugin pipeline runs.
The agent ID, path, and method are checked before authentication, so an unauthenticated caller can receive a
404 or 405 (or a 400 for an X-Xenovia-Session-Id that isn’t a UUID). The body is read only after the key is verified: a 413 for an oversized body, or a 400 for invalid content, goes only to an authenticated caller. Every key that cannot act as the agent in the URL — unknown, revoked, another agent’s that doesn’t link it, or a deleted agent’s — gets the same 401 invalid api key for this agent. A key of an agent that isn’t active yet gets 403 agent is not active: activate it in the Xenovia dashboard before sending requests. A provider misconfiguration (502) is reported only to an authenticated caller.X-Xenovia-Session-Id and X-Xenovia-Trace-Id into the response headers before the first body byte, so streaming responses still carry them.
Plugin details
1. Auth
- Accepts
x-xenovia-key: xe_...orAuthorization: Bearer xe_.... On the Anthropic-compatible routes the key may also arrive asx-api-key, which the Anthropic SDKs send. - Resolves the key against Redis (
apikey:{sha256(key)}, 5-minute TTL). On a miss it calls the control plane; a resolved identity is an HMAC-signed blob holdingagent_idandorg_id. - The key’s agent must be the agent in the URL. The one exception is a linked sub-agent: an agent’s key may call another active agent of the same organization that it links. The call then runs as the linked agent, with the calling agent recorded as its caller.
X-Xenovia-Workflow-Idonly groups calls into a workflow; it never lets a key call another agent. - A key scoped to an inline sub-agent identifies the call as that sub-agent.
- A request that still sends
x-xenovia-agent-roleis refused with400; use a sub-agent key instead. - Organization keys (
ak_...) are rejected here — they authenticate the management API, not the runtime. - Keys are never logged; only an 8-character SHA-256 prefix appears in logs.
2. Session
Five strategies, first match wins:
Turn numbers increment per session (30-minute sliding TTL). Sessions are isolated per API key for strategies 2–4, and cross-organization reuse of an explicit session ID is rejected.
3. Trace
- Opens a turn record and emits child runs: the model call, plus policy, escalation, and runtime-executed tool runs.
- Custom
X-Xenovia-Property-*headers are attached to the turn (see Traces and Remediation). - Persistence is asynchronous. Under sustained overload a record can be dropped rather than block the request.
4. Billing
There is no per-agent rate limit. The runtime checks the organization’s request allowance and returns402 when it is exhausted or billing access is restricted.
5. Enforce
One enforcement step runs four checks in order. A block at any of them skips the rest, and no model is called.- Hosted tool allow-list. Every hosted tool the request declares (web search, code execution, a remote MCP server, …) must be on the agent’s list when it has one.
- Request-stage policies. The request-stage Rego runs against the full request context. See Policies and Enforcement for the decision contract and the input schema. Policies are cached per agent and revalidated about every five minutes.
- Purpose gate. A request made with a key scoped to an inline sub-agent is judged against that sub-agent’s own capabilities. A call from an agent that links this one is also judged against the calling agent’s purpose and agent-wide capabilities. See Sub-agents.
- Guardrails. The
model_requeststage runs the agent’s guardrails and judges the agent’s own purpose, then thetool_resultguardrails check tool results new in this request.
model_response guardrails and a tool_call guardrail per proposed tool call. memory_write and context_summary guardrails run only on the decision endpoint, not on the inference routes.
Guardrails and the purpose gate are evaluated by Neon, Xenovia’s decision service.
- A
block, or a policyescalate, is answered with HTTP200and a refusal in the format of the API you called. A blocked reply or tool call is first sent back to the model once, so it can answer another way. See Blocks and refusals. - A guardrail
escalatelets the request proceed. - Every answer carries
X-Xenovia-Decision(allowed,blockedorunchecked). A blocked or unchecked one also carriesX-Xenovia-Reason, a short code such aspolicy:<rule>; the refusal itself never names the policy or guardrail. - There is no fail mode setting. When Neon can’t be reached, a stage with anything enforced on it fails closed with
503andRetry-After: 5. A stage with nothing enforced goes on unchecked (X-Xenovia-Decision: unchecked), and Monitor guardrails record the error and never block.
6. Failover
When the agent has fallback providers, the attempts run here, after enforcement. Each fallback is checked against the agent’s request-stage policies again before it’s called. Requests on the Anthropic-compatible routes never run a fallback route: they use the primary only.Supported providers
Xenovia speaks OpenAI format and Anthropic’s Messages API to your app and translates each request for the provider upstream, so your app can use an OpenAI- or Anthropic-compatible client whatever provider is behind the agent. More than forty providers are supported: model developers (OpenAI, Anthropic, Google, Mistral, xAI and others), cloud platforms (Azure OpenAI, Microsoft Foundry, Amazon Bedrock, Google Vertex AI, Databricks), inference providers, routers, self-hosted servers and any OpenAI- or Anthropic-compatible endpoint. See Supported providers for the full list and the credentials each takes. The provider your policy sees ininput.provider is the provider’s type as configured (openai, microsoft-foundry, together, …), whatever API the runtime uses to reach it. A provider configured with a custom base URL keeps its type.
Supported endpoints
The OpenAI base URL is
https://runtime.xenovia.io/{agent_id}/v1; the Anthropic base URL is https://runtime.xenovia.io/{agent_id}. The model in a request is ignored: the provider’s configured model is used.
Embeddings, legacy completions, model listing, and audio, image, video, batch, and container endpoints are not routed and return 404. Besides these inference routes, the runtime serves only the health endpoints, the decision endpoint POST /v1/execute, and the coding-agent hook endpoints. Text, image, and file inputs are accepted; requests for audio output are rejected with 400.
Security
- Credential isolation. Provider credentials live in the agent’s configuration and are resolved server-side; your app never holds them. Secrets are fetched over an internal channel and kept in memory, never written to Redis or into telemetry.
- SSRF protection. Provider base URLs are validated, and every connection to a provider is checked again against the address it resolves to. Link-local and cloud-metadata addresses are always rejected. Loopback and private addresses are rejected unless the runtime sets
XENOVIA_ALLOW_PRIVATE_PROVIDER_ENDPOINTS(see Hybrid). - Config integrity. Config snapshots and identity blobs are HMAC-signed. A revoked agent key stops working within about five minutes in the cloud.
- Deployment. In the standard cloud deployment Xenovia operates the runtime. A hybrid data-plane option runs the runtime inside your own cluster; ask your Xenovia contact for the deployment guide.