API Gateway mapping template and access logging variable reference - Amazon API Gateway
$context Variables for data models, authorizers, mapping templates, and CloudWatch access logging$context Variable template example$context Variables for access logging only$input Variables$input Variable template examples$stageVariables$util Variables

API Gateway mapping template and access logging variable reference

This section provides reference information for the variables and functions that Amazon API Gateway defines for use with data models, authorizers, mapping templates, and CloudWatch access logging. For detailed information about how to use these variables and functions, see Mapping templates for REST APIs. For more information about the Velocity Template Language (VTL), see the VTL Reference.

Note

For $method and $integration variables, see Amazon API Gateway API request and response data mapping reference.

$context Variables for data models, authorizers, mapping templates, and CloudWatch access logging

The following $context variables can be used in data models, authorizers, mapping templates, and CloudWatch access logging. API Gateway might add additional context variables.

For $context variables that can be used only in CloudWatch access logging, see $context Variables for access logging only.

Parameter Description
$context.accountId

The API owner's AWS account ID.
$context.apiId

The identifier API Gateway assigns to your API.
$context.authorizer.claims.property

A property of the claims returned from the Amazon Cognito user pool after the method caller is successfully authenticated. For more information, see Control access to REST APIs using Amazon Cognito user pools as an authorizer.

Note

Calling $context.authorizer.claims returns null.
$context.authorizer.principalId

The principal user identification associated with the token sent by the client and returned from an API Gateway Lambda authorizer (formerly known as a custom authorizer). For more information, see Use API Gateway Lambda authorizers.
$context.authorizer.property

The stringified value of the specified key-value pair of the context map returned from an API Gateway Lambda authorizer function. For example, if the authorizer returns the following context map: 

"context" : {
  "key": "value",
  "numKey": 1,
  "boolKey": true
}

Calling $context.authorizer.key returns the "value" string, calling $context.authorizer.numKey returns the "1" string, and calling $context.authorizer.boolKey returns the "true" string.

For property, the only supported special character is the underscore (_) character.

For more information, see Use API Gateway Lambda authorizers.
$context.awsEndpointRequestId

The AWS endpoint's request ID.
$context.deploymentId

The ID of the API deployment.
$context.domainName

The full domain name used to invoke the API. This should be the same as the incoming Host header.
$context.domainPrefix

The first label of the $context.domainName.
$context.error.message

A string containing an API Gateway error message. This variable can only be used for simple variable substitution in a GatewayResponse body-mapping template, which is not processed by the Velocity Template Language engine, and in access logging. For more information, see Monitor WebSocket API execution with CloudWatch metrics and Setting up gateway responses to customize error responses.
$context.error.messageString The quoted value of $context.error.message, namely "$context.error.message".
$context.error.responseType

A type of GatewayResponse. This variable can only be used for simple variable substitution in a GatewayResponse body-mapping template, which is not processed by the Velocity Template Language engine, and in access logging. For more information, see Monitor WebSocket API execution with CloudWatch metrics and Setting up gateway responses to customize error responses.
$context.error.validationErrorString

A string containing a detailed validation error message.
$context.extendedRequestId The extended ID that API Gateway generates and assigns to the API request. The extended request ID contains useful information for debugging and troubleshooting.
$context.httpMethod

The HTTP method used. Valid values include: DELETE, GET, HEAD, OPTIONS, PATCH, POST, and PUT.
$context.identity.accountId

The AWS account ID associated with the request.
$context.identity.apiKey

For API methods that require an API key, this variable is the API key associated with the method request. For methods that don't require an API key, this variable is null. For more information, see Usage plans and API keys for REST APIs in API Gateway.
$context.identity.apiKeyId The API key ID associated with an API request that requires an API key.
$context.identity.caller

The principal identifier of the caller that signed the request. Supported for resources that use IAM authorization.
$context.identity.cognitoAuthenticationProvider

A comma-separated list of all the Amazon Cognito authentication providers used by the caller making the request. Available only if the request was signed with Amazon Cognito credentials.

For example, for an identity from an Amazon Cognito user pool, cognito-idp. region.amazonaws.com/user_pool_id,cognito-idp.region.amazonaws.com/user_pool_id:CognitoSignIn:token subject claim

For information about the available Amazon Cognito authentication providers, see Using Federated Identities in the Amazon Cognito Developer Guide.
$context.identity.cognitoAuthenticationType

The Amazon Cognito authentication type of the caller making the request. Available only if the request was signed with Amazon Cognito credentials. Possible values include authenticated for authenticated identities and unauthenticated for unauthenticated identities.
$context.identity.cognitoIdentityId

The Amazon Cognito identity ID of the caller making the request. Available only if the request was signed with Amazon Cognito credentials.
$context.identity.cognitoIdentityPoolId

The Amazon Cognito identity pool ID of the caller making the request. Available only if the request was signed with Amazon Cognito credentials.
$context.identity.principalOrgId

The AWS organization ID.
$context.identity.sourceIp

The source IP address of the immediate TCP connection making the request to the API Gateway endpoint.
$context.identity.clientCert.clientCertPem

The PEM-encoded client certificate that the client presented during mutual TLS authentication. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails.
$context.identity.clientCert.subjectDN

The distinguished name of the subject of the certificate that a client presents. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails.
$context.identity.clientCert.issuerDN

The distinguished name of the issuer of the certificate that a client presents. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails.
$context.identity.clientCert.serialNumber

The serial number of the certificate. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails.
$context.identity.clientCert.validity.notBefore

The date before which the certificate is invalid. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails.
$context.identity.clientCert.validity.notAfter

The date after which the certificate is invalid. Present when a client accesses an API by using a custom domain name that has mutual TLS enabled. Present only in access logs if mutual TLS authentication fails.
$context.identity.vpcId

The VPC ID of the VPC making the request to the API Gateway endpoint.
$context.identity.vpceId

The VPC endpoint ID of the VPC endpoint making the request to the API Gateway endpoint. Present only when you have a private API.
$context.identity.user

The principal identifier of the user that will be authorized against resource access. Supported for resources that use IAM authorization.
$context.identity.userAgent

The User-Agent header of the API caller.
$context.identity.userArn

The Amazon Resource Name (ARN) of the effective user identified after authentication. For more information, see https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users.html.
$context.isCanaryRequest

Returns true if the request was directed to the canary and false if the request was not directed to the canary. Present only when you have a canary enabled.
$context.path The request path. For example, for a non-proxy request URL of https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child, the $context.path value is /{stage}/root/child.
$context.protocol The request protocol, for example, HTTP/1.1.
Note

API Gateway APIs can accept HTTP/2 requests, but API Gateway sends requests to backend integrations using HTTP/1.1. As a result, the request protocol is logged as HTTP/1.1 even if a client sends a request that uses HTTP/2.
$context.requestId

An ID for the request. Clients can override this request ID. Use $context.extendedRequestId for a unique request ID that API Gateway generates.
$context.requestOverride.header.header_name

The request header override. If this parameter is defined, it contains the headers to be used instead of the HTTP Headers that are defined in the Integration Request pane. For more information, see Use a mapping template to override an API's request and response parameters and status codes.
$context.requestOverride.path.path_name

The request path override. If this parameter is defined, it contains the request path to be used instead of the URL Path Parameters that are defined in the Integration Request pane. For more information, see Use a mapping template to override an API's request and response parameters and status codes.
$context.requestOverride.querystring.querystring_name

The request query string override. If this parameter is defined, it contains the request query strings to be used instead of the URL Query String Parameters that are defined in the Integration Request pane. For more information, see Use a mapping template to override an API's request and response parameters and status codes.
$context.responseOverride.header.header_name The response header override. If this parameter is defined, it contains the header to be returned instead of the Response header that is defined as the Default mapping in the Integration Response pane. For more information, see Use a mapping template to override an API's request and response parameters and status codes.
$context.responseOverride.status The response status code override. If this parameter is defined, it contains the status code to be returned instead of the Method response status that is defined as the Default mapping in the Integration Response pane. For more information, see Use a mapping template to override an API's request and response parameters and status codes.
$context.requestTime The CLF-formatted request time (dd/MMM/yyyy:HH:mm:ss +-hhmm).
$context.requestTimeEpoch The Epoch-formatted request time, in milliseconds.
$context.resourceId

The identifier that API Gateway assigns to your resource.
$context.resourcePath

The path to your resource. For example, for the non-proxy request URI of https://{rest-api-id}.execute-api.{region}.amazonaws.com/{stage}/root/child, The $context.resourcePath value is /root/child. For more information, see Tutorial: Create a REST API with an HTTP non-proxy integration.

$context.stage

The deployment stage of the API request (for example, Beta or Prod).
$context.wafResponseCode

The response received from AWS WAF: WAF_ALLOW or WAF_BLOCK. Will not be set if the stage is not associated with a web ACL. For more information, see Use AWS WAF to protect your REST APIs in API Gateway.
$context.webaclArn

The complete ARN of the web ACL that is used to decide whether to allow or block the request. Will not be set if the stage is not associated with a web ACL. For more information, see Use AWS WAF to protect your REST APIs in API Gateway.

$context Variable template example

You might want to use $context variables in a mapping template if your API method passes structured data to a backend that requires the data to be in a particular format.

The following example shows a mapping template that maps incoming $context variables to backend variables with slightly different names in an integration request payload:

Note

One of the variables is an API key. This example assumes that the method requires an API key.

{
    "stage" : "$context.stage",
    "request_id" : "$context.requestId",
    "api_id" : "$context.apiId",
    "resource_path" : "$context.resourcePath",
    "resource_id" : "$context.resourceId",
    "http_method" : "$context.httpMethod",
    "source_ip" : "$context.identity.sourceIp",
    "user-agent" : "$context.identity.userAgent",
    "account_id" : "$context.identity.accountId",
    "api_key" : "$context.identity.apiKey",
    "caller" : "$context.identity.caller",
    "user" : "$context.identity.user",
    "user_arn" : "$context.identity.userArn"
}

The output of this mapping template should look like the following:

{
  stage: 'prod',
  request_id: 'abcdefg-000-000-0000-abcdefg',
  api_id: 'abcd1234',
  resource_path: '/',
  resource_id: 'efg567',
  http_method: 'GET',
  source_ip: '192.0.2.1',
  user-agent: 'curl/7.84.0',
  account_id: '111122223333',
  api_key: 'MyTestKey',
  caller: 'ABCD-0000-12345',
  user: 'ABCD-0000-12345',
  user_arn: 'arn:aws:sts::111122223333:assumed-role/Admin/carlos-salazar'
}

$context Variables for access logging only

The following $context variables are available only for access logging. For more information, see Set up CloudWatch logging for REST APIs in API Gateway. (For WebSocket APIs, see Monitor WebSocket API execution with CloudWatch metrics.)

Parameter Description
$context.authorize.error The authorization error message.
$context.authorize.latency The authorization latency in ms.
$context.authorize.status The status code returned from an authorization attempt.
$context.authorizer.error The error message returned from an authorizer.
$context.authorizer.integrationLatency The authorizer integration latency in ms.
$context.authorizer.integrationStatus The status code returned from a Lambda authorizer.
$context.authorizer.latency The authorizer latency in ms.
$context.authorizer.requestId The AWS endpoint's request ID.
$context.authorizer.status The status code returned from an authorizer.
$context.authenticate.error The error message returned from an authentication attempt.
$context.authenticate.latency The authentication latency in ms.
$context.authenticate.status The status code returned from an authentication attempt.
$context.customDomain.basePathMatched

The path for an API mapping that an incoming request matched. Applicable when a client uses a custom domain name to access an API. For example if a client sends a request to https://api.example.com/v1/orders/1234, and the request matches the API mapping with the path v1/orders, the value is v1/orders. To learn more, see Map API stages to a custom domain name for REST APIs.
$context.endpointType

The endpoint type of the API.
$context.integration.error The error message returned from an integration.
$context.integration.integrationStatus For Lambda proxy integration, the status code returned from AWS Lambda, not from the backend Lambda function code.
$context.integration.latency The integration latency in ms. Equivalent to $context.integrationLatency.
$context.integration.requestId The AWS endpoint's request ID. Equivalent to $context.awsEndpointRequestId.
$context.integration.status The status code returned from an integration. For Lambda proxy integrations, this is the status code that your Lambda function code returns.
$context.integrationLatency The integration latency in ms.
$context.integrationStatus For Lambda proxy integration, this parameter represents the status code returned from AWS Lambda, not from the backend Lambda function code.
$context.responseLatency The response latency in ms.
$context.responseLength The response payload length in bytes.
$context.status The method response status.
$context.waf.error The error message returned from AWS WAF.
$context.waf.latency The AWS WAF latency in ms.
$context.waf.status The status code returned from AWS WAF.
$context.xrayTraceId

The trace ID for the X-Ray trace. For more information, see Set up AWS X-Ray with API Gateway REST APIs.

$input Variables

The $input variable represents the method request payload and parameters to be processed by a mapping template. It provides the following functions:

Variable and function Description
$input.body

Returns the raw request payload as a string. You can use $input.body to preserve entire floating point numbers, such as 10.00.
$input.json(x)

This function evaluates a JSONPath expression and returns the results as a JSON string.

For example, $input.json('$.pets') returns a JSON string representing the pets structure.

For more information about JSONPath, see JSONPath or JSONPath for Java.
$input.params()

Returns a map of all the request parameters. We recommend that you use $util.escapeJavaScript to sanitize the result to avoid a potential injection attack. For full control of request sanitization, use a proxy integration without a template and handle request sanitization in your integration.
$input.params(x)

Returns the value of a method request parameter from the path, query string, or header value (searched in that order), given a parameter name string x. We recommend that you use $util.escapeJavaScript to sanitize the parameter to avoid a potential injection attack. For full control of parameter sanitization, use a proxy integration without a template and handle request sanitization in your integration.
$input.path(x)

Takes a JSONPath expression string (x) and returns a JSON object representation of the result. This allows you to access and manipulate elements of the payload natively in Apache Velocity Template Language (VTL).

For example, if the expression $input.path('$.pets') returns an object like this:

[
  { 
    "id": 1, 
    "type": "dog", 
    "price": 249.99 
  }, 
  { 
    "id": 2, 
    "type": "cat", 
    "price": 124.99 
  }, 
  { 
    "id": 3, 
    "type": "fish", 
    "price": 0.99 
  } 
]

$input.path('$.pets').size() would return "3".

For more information about JSONPath, see JSONPath or JSONPath for Java.

$input Variable template examples

The following examples show how to use the $input variables in mapping templates. You can use a mock integration or a Lambda non-proxy integration that returns the input event back to API Gateway to try these examples.

Parameter mapping template example

The following example passes all request parameters, including path, querystring, and header, through to the integration endpoint via a JSON payload:

#set($allParams = $input.params())
{
  "params" : {
    #foreach($type in $allParams.keySet())
    #set($params = $allParams.get($type))
    "$type" : {
      #foreach($paramName in $params.keySet())
      "$paramName" : "$util.escapeJavaScript($params.get($paramName))"
      #if($foreach.hasNext),#end
      #end
    }
    #if($foreach.hasNext),#end
    #end
  }
}

For a request that includes the following input parameters:

  • A path parameter named myparam

  • Query string parameters querystring1=value1,value2&querystring2=value3

  • Headers "header1" : "value1", "header2" : "value2", "header3" : "value3".

The output of this mapping template should look like the following:

{
  "params" : {
        "path" : {
            "path" : "myparam"
                }
    ,        "querystring" : {
            "querystring1" : "value1,value2"
      ,            "querystring2" : "value3"
                }
    ,        "header" : {
            "header3" : "value3"
      ,            "header2" : "value2"
      ,            "header1" : "value1"
                }
          }
}

JSON mapping template example

You might want to use the $input variable to get query strings and the request body with or without using models. You might also want to get the parameter and the payload, or a subsection of the payload. The following three examples show how to do this.

The following example uses a mapping template to get a subsection of the payload. This example get the input parameter name and then the the entire POST body:

{
    "name" : "$input.params('name')",
    "body" : $input.json('$') 
}

For a request that includes the query string parameters name=Bella&type=dog and the following body:

{
    "Price" : "249.99",
    "Age": "6"
}

The output of this mapping template should look like the following:

{
    "name" : "Bella",
    "body" : {"Price":"249.99","Age":"6"}
}

If the JSON input contains unescaped characters that cannot be parsed by JavaScript, API Gateway might return a 400 response. Apply $util.escapeJavaScript($input.json('$')) to ensure the JSON input can be parsed properly.

The previous example with $util.escapeJavaScript($input.json('$')) applied is as follows:

{
    "name" : "$input.params('name')",
    "body" : $util.escapeJavaScript($input.json('$'))
}

In this case, the output of this mapping template should look like the following:

{
    "name" : "Bella",
    "body": {\"Price\":\"249.99\",\"Age\":\"6\"}
}

JSONPath expression example

The following example shows how to pass a JSONPath expression to the json() method. You could also read a subsection of your request body object by using a period, ., to specify a property:

{
    "name" : "$input.params('name')",
    "body" : $input.json('$.Age')  
}

For a request that includes the query string parameters name=Bella&type=dog and the following body:

{
    "Price" : "249.99",
    "Age": "6"
}

The output of this mapping template should look like the following:

{
    "name" : "Bella",
    "body" : "6"
}

If a method request payload contains unescaped characters that cannot be parsed by JavaScript, API Gateway might return a 400 response. Apply $util.escapeJavaScript() to ensure the JSON input can be parsed properly.

The previous example with $util.escapeJavaScript($input.json('$.Age')) applied is as follows:

{
    "name" : "$input.params('name')",
    "body" : "$util.escapeJavaScript($input.json('$.Age'))" 
}

In this case, the output of this mapping template should look like the following:

{
    "name" : "Bella",
    "body": "\"6\""
}

Request and response example

The following example uses $input.params(), $input.path(), and $input.json() for a resource with the path /things/{id}:

{
    "id" : "$input.params('id')",
    "count" : "$input.path('$.things').size()",
    "things" : $input.json('$.things')"
}

For a request that includes the path parameter 123 and the following body:

{
      "things": {
            "1": {},
            "2": {},
            "3": {}
      }
}

The output of this mapping template should look like the following:

{"id":"123","count":"3","things":{"1":{},"2":{},"3":{}}}

If a method request payload contains unescaped characters that cannot be parsed by JavaScript, API Gateway might return a 400 response. Apply $util.escapeJavaScript() to ensure the JSON input can be parsed properly.

The previous example with $util.escapeJavaScript($input.json('$.things')) applied is as follows:

{
     "id" : "$input.params('id')",
     "count" : "$input.path('$.things').size()",
     "things" : "$util.escapeJavaScript($input.json('$.things'))"
}

The output of this mapping template should look like the following:

{"id":"123","count":"3","things":"{\"1\":{},\"2\":{},\"3\":{}}"}

For more mapping examples, see Mapping templates for REST APIs.

$stageVariables

Stage variables can be used in parameter mapping and mapping templates and as placeholders in ARNs and URLs used in method integrations. For more information, see Use stage variables for a REST API in API Gateway.

Syntax Description
$stageVariables.<variable_name>, $stageVariables['<variable_name>'], or ${stageVariables['<variable_name>']}

<variable_name> represents a stage variable name.

$util Variables

The $util variable contains utility functions for use in mapping templates.

Note

Unless otherwise specified, the default character set is UTF-8.

Function Description
$util.escapeJavaScript()

Escapes the characters in a string using JavaScript string rules.

Note

This function will turn any regular single quotes (') into escaped ones (\'). However, the escaped single quotes are not valid in JSON. Thus, when the output from this function is used in a JSON property, you must turn any escaped single quotes (\') back to regular single quotes ('). This is shown in the following example: 

 "input" : "$util.escapeJavaScript(data).replaceAll("\\'","'")"
$util.parseJson()

Takes "stringified" JSON and returns an object representation of the result. You can use the result from this function to access and manipulate elements of the payload natively in Apache Velocity Template Language (VTL). For example, if you have the following payload: 

{"errorMessage":"{\"key1\":\"var1\",\"key2\":{\"arr\":[1,2,3]}}"}

and use the following mapping template 

#set ($errorMessageObj = $util.parseJson($input.path('$.errorMessage')))
{
   "errorMessageObjKey2ArrVal" : $errorMessageObj.key2.arr[0]
}

You will get the following output:

{
   "errorMessageObjKey2ArrVal" : 1
}
$util.urlEncode()

Converts a string into "application/x-www-form-urlencoded" format.
$util.urlDecode()

Decodes an "application/x-www-form-urlencoded" string.
$util.base64Encode()

Encodes the data into a base64-encoded string.
$util.base64Decode()

Decodes the data from a base64-encoded string.