Attested Routing

Restrict a request to an upstream the gateway verified inside the TEE, and pin it to a specific attested channel.

Attested routing restricts a request to an upstream that the gateway verified before sending the prompt. Verification runs inside the TEE, produces an enforceable channel binding, and fails closed: if no eligible upstream verifies, the prompt is never forwarded.

Use it when a prompt must not reach a provider whose execution environment you cannot check. The examples below use a confidential model; see List the models you can use to find one.

Two levels of constraint are available:

Constraint	What it selects
provider: {"aci_verified": true}	Any upstream that is currently verified and channel bound.
provider: {"aci_session_ids": [...]}	One specific attested channel, by session id.

The Phala endpoint is TEE-only: upstream verification is required even when this block is omitted. aci_verified can express that requirement explicitly, and aci_session_ids narrows it to specified verified channels. No request option disables the endpoint policy. See Provider Verification.

​

Require an attested upstream

Add the provider block to the request. Every inference endpoint accepts it: /v1/chat/completions, /v1/messages, /v1/responses, /v1/embeddings, and /v1/completions.

curl https://inference.phala.com/v1/chat/completions \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.3",
    "messages": [{"role": "user", "content": "Summarize this patient note."}],
    "provider": {"aci_verified": true}
  }'

If no upstream for the requested model is both classified as attested and currently verified, the request fails before the prompt is sent. For example, an unavailable verified route can return:

{
  "error": {
    "message": "upstream verification failed: no attested upstream available for model z-ai/glm-5.3",
    "type": "upstream_verification_failed"
  }
}

The status is 503 (upstream_verification_failed). Failover retries stay inside the attested set, so a plaintext upstream never receives the prompt as a fallback.

Setting "aci_verified": false, or omitting the field, adds no request-level constraint. The endpoint still requires verified serving.

A request that requires an attested upstream cannot also opt out of the attestation. No request header or option relaxes this constraint once aci_verified is set.

​

Pin a request to one attested channel

aci_verified accepts any upstream that is verified right now. To require one specific attested channel, pass its session id. This is useful when you have already inspected a session’s evidence and want subsequent requests to reach that exact channel or fail.

List the sessions that can serve your model. The unfiltered list covers every upstream the gateway has verified, so filter it: a session belonging to another upstream will never match your request.

curl -s "https://inference.phala.com/v1/aci/sessions?model=z-ai/glm-5.3" \
  -H "Authorization: Bearer <API_KEY>" \
  | jq -r '.sessions[] | "\(.session_id)  \(.upstream_name)  \(.endpoint)"'

Each entry carries a session_id as a bare 64-character lowercase hex digest with no prefix, the verifier that produced it, its channel binding, and an expires_at timestamp. ?upstream_name= filters the same list by upstream. See Get Session.

The most reliable id is the one that already served you. Every response’s receipt names the session that served it, so a client can pin follow-up requests to the channel it just used.

Pin a request to one or more of them. The example id below was obtained from the live sessions endpoint; replace it with a currently accepted id before sending:

curl https://inference.phala.com/v1/chat/completions \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "z-ai/glm-5.3",
    "messages": [{"role": "user", "content": "Summarize this patient note."}],
    "provider": {
      "aci_verified": true,
      "aci_session_ids": ["50b1e4ac17b1f10906595d322269b69e75ba15e03adb147490fa28eba4de8fc1"]
    }
  }'

Listing several ids means any one of them may serve the request. If none of them matches a currently verified channel, the request fails with 412 (session_not_accepted) and no prompt is sent:

{
  "error": {
    "message": "upstream verification failed: none of the requested attested sessions is available for model z-ai/glm-5.3",
    "type": "session_not_accepted"
  }
}

A session id is tied to one verified channel, and the gateway re-verifies periodically. When it re-verifies, the evidence changes and the id changes with it. Read a current id shortly before you pin it, and expect a pinned id to stop matching. A pin that stops matching is a failure, never a silent fallback to a different channel.

aci_session_ids implies aci_verified. Passing session ids together with "aci_verified": false is rejected as a contradiction rather than resolved in either direction.

​

List the models you can use

curl -s "https://inference.phala.com/v1/models?tee=true" \
  | jq -r '.data[].id'

Embedding models have their own catalog, which takes the same parameter:

curl -s "https://inference.phala.com/v1/embeddings/models?tee=true" \
  | jq -r '.data[].id'

true is the only accepted value. Any other value, including false, returns 400. Omit the parameter for the full catalog.

?tee=true and provider: {"aci_verified": true} read different properties. The catalog filter reports a model’s own is_tee capability flag. The routing constraint is enforced against the provider actually serving the request.

A model listed under ?tee=true can still return 503 for an attested request when none of its live deployments is on an attested provider. The catalog tells you which models are offered confidentially. Only the gateway decides what a given request may reach.

​

Request validation

The gateway parses the attestation fields itself and rejects anything it cannot read, rather than treating it as an absent constraint. Every case below returns 400 with type invalid_request_error and forwards nothing.

Request	Result
"provider": {"aci_verified": true}	Constraint applied.
"provider": {"aci_verified": false}	No extra request constraint; endpoint policy still applies.
"provider": {"aci_verified": "yes"}	400, expected a boolean.
"provider": {"aci_session_ids": []}	400, must not be empty.
"provider": {"aci_session_ids": [""]}	400, expected non-empty strings.
"provider": {"aci_verified": false, "aci_session_ids": ["<64 lowercase hex>"]}	400, contradictory.
"provider": ["aci_verified"]	400, the block must be an object.

aci_verified and aci_session_ids are read by the gateway and removed before the request reaches a provider. They compose with the other provider fields, such as zdr.

​

What the constraint guarantees

The check runs before any prompt bytes leave the gateway:

1. The route is classified as an attested provider.
2. Verification is required for that route and cannot be waived by the request.
3. Verification returns a verified result and an enforceable channel binding.
4. The request is forwarded over the bound channel.

Verification evidence is cached for a short interval and refreshed in the background, so a verified result may come from a recent check rather than one performed at that instant. The channel binding is enforced on every connection. If the upstream presents a key or certificate that does not match the binding, the gateway re-verifies and retries, then fails. A request is never served over a channel that does not match the evidence it was verified against.

This constraint applies per request. There is no session to establish and reuse: every request is evaluated on its own, and each failover candidate is evaluated independently.

​

Verify that it held

A successful attested request returns x-receipt-id. Fetch that receipt and read its upstream.verified event:

curl -s "https://inference.phala.com/v1/aci/receipts/$RECEIPT_ID" \
  -H "Authorization: Bearer <API_KEY>" \
  | jq '.event_log[] | select(.type == "upstream.verified")'

{
  "type": "upstream.verified",
  "model_id": "z-ai/glm-5.3",
  "result": "verified",
  "required": true,
  "session_id": "50b1e4ac17b1f10906595d322269b69e75ba15e03adb147490fa28eba4de8fc1"
}

These fields record the gateway’s assertion that the constraint held. Inspection alone does not verify it; verify the receipt signature, hashes, and cited session with the TypeScript SDK or Private AI Proxy. session_id names the channel that served the request, and is the id to pin for follow-up requests. The cited session holds channel_binding, typed claims, and evidence; inspect its upstream_name rather than assuming a catalog provider name. See Verify a Response.

The request you sent is bound into the same receipt through request.received.body_hash, so you can prove which constraint you asked for alongside the result you got.

​

Related

Receipts and Sessions

What a session id identifies and how long it lives.

Channel Binding

How a verified channel is enforced on the wire.

Zero Data Retention

The retention constraint, which composes with this one.

Chat Completions

The full provider routing block.