Request context

CEL reference for request, response, source, env, jwt, apiKey, basicAuth, backend, and metadata context objects.

Request context

This page documents the CEL context objects available for HTTP request and response processing in Agentgateway. These objects are available across authorization rules, transformations, logging, and tracing expressions.

request

The request object contains attributes about the incoming HTTP request.

request.method · string

The HTTP method of the request.

request.method == "GET"
request.method in ["POST", "PUT", "PATCH"]

request.uri · string

The complete URI of the request, including scheme, host, path, and query string. Supports .query(), .addQuery(), and .setQuery() methods.

request.uri == "http://example.com/api/users"
request.uri.query("page") == ["2"]
request.uri.setQuery("version", "2")

request.host · string

The hostname of the request.

request.host == "api.example.com"

request.scheme · string

The scheme of the request (http or https).

request.scheme == "https"

request.path · string

The path component of the request URI, without query string.

request.path == "/api/v1/users"
request.path.startsWith("/admin")

request.pathAndQuery · string

The path and query string of the request URI. Supports .query(), .addQuery(), and .setQuery() methods.

request.pathAndQuery == "/api/users?page=2"
request.pathAndQuery.query("filter") == ["active"]

request.version · string

The HTTP version of the request.

request.version == "HTTP/1.1"
request.version == "HTTP/2.0"

request.headers · object

The headers of the request. Returns a string for single-value headers and a list for multi-value headers. Supports .redacted(), .join(), .raw(), .split(), and .cookie(name) methods.

request.headers["content-type"] == "application/json"
request.headers["x-api-key"]
request.headers.cookie("session")
request.headers.join()["x-forwarded-for"]

request.body · string

The body of the request as a string.

Accessing request.body causes the body to be buffered in memory. Only reference this field when necessary, as it has performance implications for large payloads.

json(request.body).user_id == "abc123"
json(request.body).action in ["read", "list"]

request.startTime · string

The timestamp when the request started, as an RFC3339 string. Use timestamp() to parse for time arithmetic.

timestamp(request.startTime).getHours() >= 9

request.endTime · string

The timestamp when the request completed. Only available after the response has been received.

timestamp(request.endTime).getHours() < 17

---

response

The response object contains attributes about the HTTP response. It is only available in response-phase expressions (for example, logging and response transformations) — not during request-phase authorization.

response.code · integer

The HTTP status code of the response.

response.code == 200
response.code >= 400
response.code >= 500

response.headers · object

The headers of the response. Supports the same chainable methods as request.headers.

response.headers["content-type"] == "application/json"
response.headers.redacted()["set-cookie"]

response.body · string

The body of the response as a string.

Accessing response.body causes the body to be buffered in memory. Only reference this field when necessary, as it has performance implications for large responses.

json(response.body).error == "unauthorized"

---

source

The source object contains attributes about the downstream connection — the client that sent the request.

source.address · string

The IP address of the downstream connection.

source.address == "192.168.1.10"
cidr("10.0.0.0/8").containsIP(source.address)
!cidr("192.168.0.0/16").containsIP(source.address)

source.port · integer

The port of the downstream connection.

source.port == 8080

source.identity · object

The Istio SPIFFE identity of the downstream connection. Only present when mTLS is enabled and the downstream presents a valid certificate.

Show identity fields

source.identity.trustDomain · string

The trust domain of the SPIFFE identity. For example, cluster.local.

source.identity.trustDomain == "cluster.local"

source.identity.namespace · string

The Kubernetes namespace from the SPIFFE identity.

source.identity.namespace == "production"

source.identity.serviceAccount · string

The Kubernetes service account from the SPIFFE identity.

source.identity.serviceAccount == "my-agent"

source.subjectAltNames · string[]

The Subject Alternative Names from the downstream client certificate, if available.

"spiffe://cluster.local/ns/default/sa/my-agent" in source.subjectAltNames

source.issuer · string

The issuer from the downstream client certificate, if available.

source.issuer == "O=My CA,CN=Root CA"

source.subject · string

The subject from the downstream client certificate, if available.

source.subject.contains("O=My Org")

source.subjectCn · string

The Common Name (CN) from the subject of the downstream client certificate, if available.

source.subjectCn == "my-service.example.com"

---

env

The env object exposes a curated subset of Kubernetes environment attributes. It does not expose raw environment variables.

env.podName · string

The name of the pod, when running on Kubernetes.

env.podName

env.namespace · string

The Kubernetes namespace of the pod.

env.namespace == "production"

env.gateway · string

The name of the Gateway resource the proxy is running as, when running on Kubernetes.

env.gateway == "main-gateway"

---

jwt

The jwt object contains the claims from a verified JWT token. All standard and custom claims from the token payload are accessible as fields.

jwt is only available when the JWT authentication policy is enabled for the route. The token is verified against the configured issuer and JWKS before the claims are made available.

# Standard claims
jwt.sub == "user-123"
jwt.iss == "https://auth.example.com"

# Custom claims
jwt.role == "admin"
jwt.org_id == "acme"

# Nested custom claims
jwt.nested.key == "value"

# Combine with other context
jwt.sub == "test-user" && mcp.tool.name == "add"

---

apiKey

The apiKey object contains information about a verified API key. Only present when the API key authentication policy is enabled.

apiKey.key · string

The verified API key value.

apiKey.key == "my-secret-key"

---

basicAuth

The basicAuth object contains credentials from a verified HTTP Basic authentication header. Only present when the basic authentication policy is enabled.

basicAuth.username · string

The username from the Basic authentication credentials.

basicAuth.username == "alice"
basicAuth.username in ["alice", "bob"]

---

backend

The backend object contains information about the backend selected to handle the request.

backend.name · string

The name of the backend being used.

backend.name == "my-mcp-server"
backend.name == "service/production/api:8080"

backend.type · string

The type of the backend. One of: ai, mcp, static, dynamic, service, unknown.

backend.type == "ai"
backend.type == "mcp"
backend.type in ["ai", "mcp"]

backend.protocol · string

The protocol of the backend. One of: http, tcp, a2a, mcp, llm.

backend.protocol == "mcp"
backend.protocol == "llm"

---

extauthz, extproc, and metadata

extauthz · object

Dynamic metadata set by external authorization (ext_authz) filters. Fields depend on what the external authorization service returns.

extauthz.user_id == "alice"

extproc · object

Dynamic metadata set by external processing (ext_proc) filters. Fields depend on what the external processor returns.

extproc.decision == "allow"

metadata · object

Values set by transformation metadata expressions in the Agentgateway configuration. Use this to pass computed values between transformation stages.

metadata.computed_user_id

---

Practical examples

Authorization: restrict by IP and JWT role

cidr("10.0.0.0/8").containsIP(source.address) && jwt.role == "internal"

Logging: capture user identity

# In a logging policy, define named fields:
# user_id: 'jwt.sub'
# user_agent: 'request.headers["user-agent"]'
# path: 'request.path'
# status: 'response.code'

Transformation: rewrite a header using a JWT claim

# Set the x-user-id header from the JWT subject
jwt.sub

Tracing: sample only slow or error responses

response.code >= 500 || random() < 0.05

Parse a JSON body field

json(request.body).action == "delete"
json(request.body).with(b, b.user + "-" + b.tenant)

Check a cookie value

request.headers.cookie("session") == "my-session-token"