API Connect context variables

List of IBM® API Connect context variables that you can reference when defining default parameter values in an assembly operation, or by using the getContext() function when defining a policy.

The following tables are presented:

General context variables.
OAuth context variables - DataPower Gateway (v5 compatible).
Application certificate context variables.
API activity logging context variables.
GraphQL context variables.

For more information about implementing an assembly component, see Including elements in your API assembly, and for information about how to reference context variables in API Connect see Variable references in API Connect and Using context variables in GatewayScript and XSLT policies with the DataPower API Gateway.

For more information about creating a user-defined policy, see Authoring policies.

General context variables

Note:

For plan variables (such as plan.name or plan.version), plan information is available only when the requested operation requires identification and the client passes the authentication check.
If you deploy your API to the DataPower® Gateway (v5 compatible) then, with the exception of client ID and client secret, the passing of form input as a parameter into an API is not supported. This restriction does not apply if you deploy your API to the DataPower API Gateway.

Table 1. API Connect context variables
Name	Description	Permission
`api.catalog.id`	The ID of the Catalog in which the API is published.	Read/write
`api.catalog.name`	The name of the Catalog in which the API is published.	Read/write
`api.catalog.path`	The path segment that represents this Catalog.	Read/write
`api.endpoint.address`	The address of the API Gateway endpoint.	Read/write
`api.endpoint.hostname`	The host name of the API Gateway endpoint, as requested by the application.	Read/write
`api.id`	The identifier of the API.	Read/write
`api.name`	The name of the API; this corresponds to the `x-ibm-name` field in the OpenAPI definition for the API.	Read/write
`api.operation.id`	The ID of the operation.	Read/write
`api.operation.path`	The path of the operation.	Read/write
`api.org.id`	The organization ID of the API provider.	Read/write
`api.org.name`	The organization short name of the API provider.	Read/write
`api.properties.propertyname`	The name of a custom API property. Property values are Catalog specific. Note: You have write permission to a custom property only from the user interface, not from GatewayScript. To access a Catalog specific property value from GatewayScript, you must refer to the property by using the following syntax: `apim-catalog-name` where `catalog` is the name of the Catalog, and `name` is the property name. For example: `var mypropertyvalue = $(apim-mycatalog-mypropertyname)`	Read/write
`api.root`	The API base path.	Read/write
`api.type`	The API type; REST or SOAP.	Read/write
`api.version`	The version string of the API.	Read/write
`client.app.id`	The client ID or application key that is received on the request.	Read/write
`client.app.lifecycle-state`	The lifecycle status of the calling client application. The possible values are as follows: `DEVELOPMENT` `PRODUCTION` (default)	Read/write
`client.app.metadata.key`	The string value of an application metadata key, where `key` is the name of the key. You can add metadata keys to an application by using either the apic apps:create or the apic apps:update command; you include the metadata keys in the configuration file parameter that is passed to the command. For example: `apic apps:create myapp.yaml --server myserver.com --org myorg --catalog mycatalog --consumer-org mycorg` where myapp.yaml contains the following: `name: myapp title: My test application metadata: key1: value1 key2: value2 key3: value3 key4: value4 key5: value5` You can then retrieve the value of a metadata key in an API assembly policy by using a context variable such as the following: `client.app.metadata.key3` Note that adding application metadata might impact gateway trans performance.	Read/write
`client.app.name`	The name of the application that is identified as having issued the request.	Read/write
`client.app.secret`	The client secret that is received in the request.	Read/write
`client.app.type`	The type of the client application that issued the request.	Read/write
`client.org.id`	The unique identification key of the organization that owns this application.	Read/write
`client.org.name`	The name of the organization that owns this application.	Read/write
`client.result`	The result of the client security policy, which is `SUCCESS` or `FAILURE`.	Read/write
`client.third_party.type`	The type of user registry used for third-party authentication of the extracted client credentials. The possible values are `LDAP` and `auth-url`.	Read/write
`client.third_party.headers`	The array of headers added to the request that was sent to that API authentication URL during third-party authentication.	Read/write
`client.third_party.response.authenticated`	The third-party authentication results. The possible values are as follows: `true`: the authentication was successful. `false`: the authentication failed.	Read/write
`client.third_party.response.user`	The user for third-party authentication.	Read/write
`client.title`	The title for the credentials that are received in the request.	Read/write
`env.name`	The name of the Catalog in which the API is published.	Read/write
`env.path`	The path segment that represents this Catalog.	Read/write
`error.message`	The message text for the error.	Read/write
`error.name`	The name of the error.	Read-only
`log`	The transaction data gathered in an assembly log action.	Read/write
`message.body`	The payload of the request or response message. Note: The `message.body` context variable is not supported with `getContext()` function. Use the `getvariable()` function instead.	Read/write
`message.headers.name`	The value of the current named header of the message or of the current named header of the root part of a multipart message. The `name` segment is case-insensitive.	Read/write
`message.original.headers.name`	The value of the original named header of the HTTP message. When the assembly contains an invoke action, the value is automatically populated by the original named header of the response message from the invoked URL. The `name` segment is case-insensitive.	Read-only
`message.package.headers.name`	The value of the current named header of the multipart message. The `name` segment is case-insensitive.	Read/write
`message.status.code`	The HTTP status code of the response.	Read/write
`message.status.reason`	The HTTP reason phrase of the response.	Read/write
`message.variables.name`	The value of a property in the message. For example, when `myvar` is the property in the message, you can retrieve the value of the `myvar` property by reading `message.variables.myvar`.	Read/write
`plan.name`	The name of the plan.	Read/write
`plan.id`	The unique identifier of the plan.	Read/write
`plan.rate-limit`	The rate limit of the plan, which is the number of API calls per time interval.	Read/write
`plan.rate-limit[index].hard-limit`	The hard limit setting for the rate limit scheme that is identified by `[index]`.	Read/write
`plan.rate-limit[index].value`	The value of the rate limit scheme that is identified by `[index]`. The syntax is `rate/interval`.	Read/write
`plan.spaceId`	The unique identifier of the space that the plan is contained within.	Read/write
`plan.spaceName`	The name of the space that the plan is contained within.	Read/write
`plan.version`	The version number of the plan.	Read/write
`request.authorization`	The parsed HTTP `authorization` header.	Read-only
`request.body`	The payload from the incoming request.	Read-only
`request.content-type`	Normalized content-type value.	Read-only
`request.date`	A date object that represents approximately when the request was received by the Gateway.	Read-only
`request.headers.name`	The value of the original named header of the HTTP request, or the value of the current named header of the root part of a multipart request. The `name` segment is case-insensitive. The request header can be modified only in preflow policies. For more information, see Customizing the preflow policies.	Read/write
`request.original.headers.name`	The value of the original named header of the HTTP request. This variable is created only when the request header is modified. The `name` segment is case-insensitive.	Read-only
`request.original.parameters.name.values`	An array containing the original values of the parameter types associated with the parameter specified in `name`. This variable is created only when a request parameter value is modified.	Read-only
`request.package.headers.name`	The value of the named header of the multipart request. The `name` segment is case-insensitive.	Read-only
`request.parameters`	You can obtain your incoming parameters from path and query parameters.
`request.parameters.name.locations`	An array of strings that specify the parameter types associated with the parameter specified in name. The supported keywords for parameter types are as follows. `formData` The parameter is in the body as form data `header` The parameter is in the request header `path` The parameter is in the path `query` The parameter is in the query	Read-only
`request.parameters.name.values`	An array containing values of the parameter types associated with the parameter specified in name. For example, when the first value is `path` in `request.parameters.myparam.locations[]`, the first value in `request.parameters.myparam.values[]` is the array of path values associated with `myparam`. Request parameters can be modified only in preflow policies. For more information, see Customizing the preflow policies.	Read/write
`request.path`	The path section of the `request.uri` that starts with the base path of the API, including the '/' character that begins the base path.	Read-only
`request.protocol`	The protocol that is used to receive the request: `http` or `https`.	Read-only
`request.querystring`	The request query string without the leading question mark.	Read-only
`request.search`	The request query string with the leading question mark.	Read-only
`request.uri`	The full HTTP request URI from the application.	Read-only
`request.verb`	The HTTP verb of this request.	Read-only
`session.apiGateway`	The gateway that receives the request.	Read-only
`session.apiGatewayName`	The name of the API gateway as defined in the API Manager.	Read-only
`session.clientAddress`	The address of the client that sent the request.	Read-only
`session.domainName`	The name of the domain that the gateway belongs to.	Read-only
`session.globalTransactionID`	The global transaction ID in the logs.	Read-only
`session.localAddress`	The address of the gateway on the DataPower® Gateway.	Read-only
`session.timeStarted`	The time that the gateway started to process the request.	Read-only
`session.transactionID`	The transaction ID of the gateway request.	Read-only
`system.datetime`	Returns a string that represents the current date and time in the system time zone of the gateway.	Read-only
`system.time`	Returns a string that represents the current time in the system time zone of the gateway.	Read-only
`system.time.hour`	Returns a number 0 - 23 inclusive, representing the hour of the current time in the system time zone of the gateway.	Read-only
`system.time.minute`	Returns a number 0 - 59 inclusive representing the minute of the current time in the system time zone of the gateway.	Read-only
`system.time.seconds`	Returns a number 0 - 59 inclusive representing the seconds of the current time in the system time zone of the gateway.	Read-only
`system.date`	Returns a string that represents the current date in the system time zone of the gateway.	Read-only
`system.date.day-of-week`	Returns a number 1 - 7 (Monday to Sunday) inclusive representing the day of the week in the system time zone of the gateway.	Read-only
`system.date.day-of-month`	Returns a number 1 - 31 representing the day of the month in the system time zone of the gateway.	Read-only
`system.date.month`	Returns a number 1 - 12 representing the month in the system time zone of the gateway.	Read-only
`system.date.year`	Returns a four-digit number that represents the year in the system time zone of the gateway.	Read-only
`system.timezone`	Returns a system time zone ISO 8601 identifier for the gateway, which might include a sign, a two-digit hour, and minutes. For example, `-04:00`.	Read-only

OAuth context variables - DataPower Gateway (v5 compatible)

The OAuth context variables described in this section apply only to the DataPower Gateway (v5 compatible). For details of the OAuth context variables that apply to the DataPower API Gateway, see OAuth context variables.

Table 2. OAuth context variables (DataPower Gateway (v5 compatible)).
Note: Most OAuth context variables are available only when IBM API Connect is acting as the OAuth resource server. However, the `oauth.introspect` variables are also available when integrating with third party providers.
Name	Description
`oauth.access-token`	If the request is authenticated with OAuth, this variable contains the access token string.
`oauth.miscinfo`	This variable contains information explicitly included in the Authentication URL and Metadata URL headers. For more information, see Authenticate URL.
`oauth.not-after`	If the request is authenticated with OAuth, this variable contains the date when the token expires.
`oauth.not-before`	If the request is authenticated with OAuth, this variable contains the date when the token was issued.
`oauth.resource-owner`	If the request is authenticated with OAuth, this variable contains the name of the resource owner.
`oauth.scope`	If the request is authenticated with OAuth, this variable contains the scope of this access token.
`oauth.introspect.active`	Always available to introspection. Boolean value.
`oauth.introspect.response`	Always available to introspection. Shows the complete current response payload. Example payload value: `{“active”:true, “client_id”, “xxx-xxx”, “token_type”, “bearer”, “scope”:“neon”}`
Other variables might be available from the third party, in the form of: `oauth.introspect.<variable>`	Decoding the previous example payload, the following variables are made available for further processing. `oauth.introspect.client_id: xxx-xxx oauth.introspect.token_type: bearer oauth.introspect.scope: neon`

Application certificate context variables

The following table describes context variables that are available when a certificate is used to verify access to an API, although these will vary depending on the signature mechanism that is being used; for more information, see the Internet X.509 Public Key Infrastructure Certificate and CRL Profile specification.

Table 3. Application certificate context variables
Name	Description
`application.certificate.Base64`	Base64 format.
`application.certificate.fingerprint`	Fingerprint
`application.certificate.Version`	Version
`application.certificate.SerialNumber`	Serial number
`application.certificate.SignatureAlgorithm`	Signing algorithm
`application.certificate.Issuer`	The issuer of the certificate
`application.certificate.Subject`	Subject
`application.certificate.NotBefore`	Not valid before this date
`application.certificate.NotAfter`	Not valid after this date
`application.certificate.SubjectPublicKeyAlgorithm`	Algorithm for the subject public key
`application.certificate.SubjectPublicKeyBitLength`	Length for the subject public key
`application.certificate.KeyValue.type`	Various context variables that depend on the algorithm and key. The following are possible context variables: `application.certificate.KeyValue.RSAKeyValue.Modulus` `application.certificate.KeyValue.RSAKeyValue.Exponent`

API activity logging context variables

If activity logging is enabled for an API, a log context variable is created; the log context variable contains the data relating to an API execution event. On completion of API execution, the log context variable is written to an API event record that is stored for subsequent access by API analytics. For details of the fields contained in the log context variable, see API event record fields.

The way in which you enable and configure activity logging depends on the type of gateway you are using, as follows:

If you are using the DataPower API Gateway, you configure activity logging in the API configuration settings; see Configuring activity logging (OpenAPI 2.0) or Configuring activity logging (OpenAPI 3.0).
If you are using the DataPower Gateway (v5 compatible), you configure activity logging by adding an Activity Log policy to the API assembly.

The activity logging configuration defines the default content of the log context variable, but you can modify it in an API assembly; for example:

Add your own data values by using a Set Variable policy.
Remove or redact data values by using a Redaction policy; see Redaction - DataPower API Gateway or Redaction - DataPower Gateway (v5 compatible).
Modify or replace the log context variable by using a Log policy.

GraphQL context variables

The GraphQL query and response variables generated from API processing and assembly actions are stored in the API context in the message.attributes.graphql context variables.

Table 4. GraphQL context variables
Name	Description
`message.attributes.graphql`	The query and response attributes of the GraphQL message.
`message.attributes.graphql.query`	The attributes of a GraphQL query, including the query string, operation name, and variables.
`message.attributes.graphql.query.query`	The GraphQL query string.
`message.attributes.graphql.query.variables`	The map of GraphQL variables.
`message.attributes.graphql.query.operationName`	The name of the operation to execute.
`message.attributes.graphql.query.operationType`	The type of the operation to execute.
`message.attributes.graphql.request`	The attributes of the GraphQL request.
`message.attributes.graphql.request.fieldCost`	The weighted sum of the cost of all fields accessed in the query. The cost of each field access is configured in the schema. This count includes fields whose field costs are not set to 0.0.
`message.attributes.graphql.request.fieldCounts`	The maximum number of times that each field can be retrieved by the given query. This number is equal to the number of times that the resolver responsible for producing the value of the field is required to run. This count includes fields whose field costs are not set to 0.0.
`message.attributes.graphql.request.typeCost`	The weighted sum of the cost of all types retrieved in the query. The cost of each type is configured in the schema. This count includes types whose type costs are not set to 0.0.
`message.attributes.graphql.request.typeCounts`	The maximum number of times that a value of each type can be retrieved by the given query. This count includes types whose type costs are not set to 0.0.
`message.attributes.graphql.response.fieldCost`	The weighted sum of the cost of all fields in the response to the query. The cost of each field access is configured in the schema. If this sum cannot be calculated based on the analysis configuration in the request, the field cost is expressed as the maximum integer value that can be assigned.
`message.attributes.graphql.response.fieldCounts`	The number of times that each field was retrieved in the response to the query. This number is equal to the number of times that the resolver responsible for producing the value of the field is required to run. If this sum cannot be calculated based on the analysis configuration in the request, the field count is expressed as the maximum integer value that can be assigned.
`message.attributes.graphql.response.typeCost`	The weighted sum of the cost of all types in the response to the query. The cost of each type is configured in the schema. If this sum cannot be calculated based on the analysis configuration in the request, the type cost is expressed as the maximum integer value that can be assigned.
`message.attributes.graphql.response.typeCounts`	The number of times that a value of each type was contained in the response to the query. If this sum cannot be calculated based on the analysis configuration in the request, the type count is expressed as the maximum integer value that can be assigned.
`message.attributes.parse.GraphQLIntrospection`	The introspection type of the assembly GraphQL introspect action. When a GraphQL query is parsed, this context variable is populated with one of the following values: `not-introspection` `custom-introspection` `default-introspection`