Skip to main content

​
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.
​
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

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

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

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

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

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