API Connect context variables

List of 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:

For more information about implementing an assembly component, see Including components in your assembly, and for information about how to reference context variables in IBM API Connect see Variable references in API Connect.

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

Context variables

Note:
  • Although some context variables can be used with both the DataPower® Gateway and the Micro Gateway, some context variables are restricted to a particular Gateway or return results in a different format depending on the Gateway. Restrictions or differences are marked with the following icons:
    • DataPower Gateway onlyIndicates that the context variable is available only on the DataPower Gateway.
    • Micro Gateway onlyIndicates that the context variable is available only on the Micro Gateway.
  • 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.
  • With the exception of client ID and client secret, the passing of form input as a parameter into an API is not supported.
  • IBM API Connect Micro Gateway is deprecated in IBM API Connect Version 5.0.8 in favor of DataPower Gateway. From 1 April 2020, Micro Gateway, and associated toolkit CLI commands, will no longer be supported. Existing users can migrate their API definitions to IBM DataPower Gateways. For information on supported API policies, see Built-in policies.
Table 1. API Connect context variables
Name Description Permissions
api.name The name of the API; this corresponds to the x-ibm-name field in the OpenAPI (Swagger 2.0) definition for the API. Read/write
api.document The OpenAPI (Swagger 2.0) document. Read/write
DataPower Gateway onlyapi.root

DataPower Gateway onlyThe API basePath.

Micro Gateway onlyUse api.document.basepath for the API basePath.

 Read/write
api.version The version string of the API. 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
[V5.0.1 or later]api.operation.id [V5.0.1 or later]The ID of the operation. [V5.0.1 or later]Read/write
[V5.0.1 or later]api.operation.path [V5.0.1 or later]The path of the operation. [V5.0.1 or later]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.type The API type; REST or SOAP. 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
client.app.name The name of the application that is identified as having issued the request. Read/write
client.app.id The client ID or application key that is received on the request. Read/write
client.app.secret The client secret that is received in the request. Read/write
[V5.0.7 or later]client.app.type [V5.0.7 or later]The status of the calling client application. The possible values are as follows:
  • Development
  • Production (default)
For more information, see Managing the application lifecycle.		 [V5.0.7 or later]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
env.path The path segment that represents this Catalog. Read/write
message.body The payload of the request or response message.
DataPower Gateway onlyNote: 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.status.code The HTTP status code of the response. Read/write
message.status.reason The HTTP reason phrase of the response. Read/write
plan.name The name of the plan. Read/write
plan.id The unique identifier of the plan. Read/write
plan.version The version number of the plan. Read/write
plan.rate-limit The rate limit (the number of API calls per time interval) 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.headername 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 headername segment is case-insensitive.

 Read-only
request.parameters You can obtain your incoming parameters from path and query parameters. Read-only
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.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
system.datetime Returns a string that represents the current date and time in the system time zone of the gateway. Read-only
system.time

DataPower Gateway onlyReturns a string that represents the current time in the system time zone of the gateway.

Micro Gateway onlyReturns the current time in the system time zone of the gateway in a JSON object.

 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

DataPower Gateway onlyReturns a string that represents the current date in the system time zone of the gateway.

Micro Gateway onlyReturns a JSON object 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
Table 2. OAuth context variables.
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 Permissions
DataPower Gateway onlyoauth.access-token If the request is authenticated with OAuth, this variable contains the access token string. Read/write
[V5.0.6 or later]DataPower Gateway onlyoauth.miscinfo [V5.0.6 or later]This variable contains information explicitly included in the following headers:
Authenticate URL Metadata URL
 [V5.0.6 or later]Read/write
DataPower Gateway onlyoauth.not-after If the request is authenticated with OAuth, this variable contains the date when the token expires. Read/write
DataPower Gateway onlyoauth.not-before If the request is authenticated with OAuth, this variable contains the date when the token was issued. Read/write
DataPower Gateway onlyoauth.resource-owner If the request is authenticated with OAuth, this variable contains the name of the resource owner. Read/write
DataPower Gateway onlyoauth.scope If the request is authenticated with OAuth, this variable contains the scope of this access token. Read/write
oauth.introspect.active Always available. Boolean value. Read/write
oauth.introspect.response Always available. Shows the complete current response payload. Example payload value: {“active”:true, “client_id”, “xxx-xxx”, “token_type”, “bearer”, “scope”:“neon”} Read/write
Other variables might be available from the third party, in the form of: oauth.introspect.<variable> Decoding the example above, the following variables are made available for further processing.
oauth.introspect.client_id: xxx-xxx 
oauth.introspect.token_type: bearer
oauth.introspect.scope: neon
 Read/write
[V5.0.8 or later]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 Permissions
application.certificate.Base64 Base64 format. Read-only
application.certificate.fingerprint Fingerprint Read-only
application.certificate.Version Version Read-only
application.certificate.SerialNumber Serial number Read-only
application.certificate.SignatureAlgorithm Signing algorithm Read-only
application.certificate.Issuer The issuer of the certificate Read-only
application.certificate.Subject Subject Read-only
application.certificate.NotBefore Not valid before this date Read-only
application.certificate.NotAfter Not valid after this date Read-only
application.certificate.SubjectPublicKeyAlgorithm Algorithm for the subject public key Read-only
application.certificate.SubjectPublicKeyBitLength Length for the subject public key Read-only
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
 Read-only