Connection Merge API Reference

When configuring Nintex Apps connections and authentication providers, additional merge variables are added to the Merge API that allow you to access information about the connection's authentication configuration and current state.

There are a number of places in connection and authentication provider configuration that process Nintex Apps's Merge API, which we'll give examples of here as well.

$Auth

$Auth.Username

At runtime, inserts the org-wide, profile, or running user's username, subject to the connection's configured Credential Source policy.

Example: Connection Credential Source = "Shared: Org-wide".

In this case, {{$Auth.Username}} will resolve to the Org-Wide default Username defined on the connection.

Example: Connection Credential Source = "Per-User, with optional Profile / Org-wide Defaults".

If the running user has entered their own username / password for a given connection, then {{$Auth.Username}} will resolve to the user's username. However, if the running user has NOT entered credentials, then Nintex Apps will fall back on profile and org-wide Defaults:

If there is a profile default credential, this will be used.
If not, then an org-wide default will be used.
If there are no credentials at any level, {{$Auth.Username}} will fail to resolve.

$Auth.Password

At runtime, $Auth.Password inserts the org-Wide, profile, or running user's password, subject to the connection's configured Credential Source policy. For instance, if the connection's Credential Source is Shared: Org-wide, this will retrieve the Org-Wide default Username defined on the connection.

$Auth.BasicAuth

Inserts a base-64 encoded hash of the org-wide, profile, or running user's username and password according to the HTTP Basic Authentication specification, for easy inclusion in an "Authorization" request header.

For example, if the user's username and password are joe@example.com and "password123", {{$Auth.BasicAuth}} will evaluate to:

"Basic am9lQGV4YW1wbGUuY29tOnBhc3N3b3JkMTIz"

using the formula: "Basic " + base64encode(<Username> + ":" + <Password>)

$Auth.Response.Headers

Allows access to the headers returned in the response to the authentication request for the connection. This merge is useful for retrieving access tokens returned after successful authentication attempts.

This merge is mainly useful for connections that use the "Separate Authentication URL" or "Authentication Provider" authentication methods.

EXAMPLE

To connect to Dunn and Bradstreet's REST API, you must first make an initial authentication request to " https://maxcvservices.dnb.com/rest/Authentication ", passing in two headers: "x-dnb-user": {{$Auth.Username}} and "x-dnb-pwd": " {{$Auth.Password}}. This authentication request returns an HTTP response with a header named "Authorization", which contains an "access token" that must be supplied in all subsequent requests to DNB's REST API.
To get Nintex Apps to add an "Authorization" Header to all subsequent requests to DNB's REST API, you must add a "Common Request Header". For the header name, enter "Authorization", and for the header value, enter {{$Auth.Response.Headers.Authorization}}. This retrieves the value of the "Authorization" header that was returned in the authentication response. All authentication response headers are accessible by name through this property.

$Auth.Response.Body

This merge allows access to parameters returned in the body of the response to the authentication request for the connection. Useful for retrieving access tokens returned after successful authentication attempts.

This merge is mainly useful for connections that use the "Separate Authentication URL" or "Authentication Provider" authentication methods.

EXAMPLE 1: response body in "application/x-www-form-urlencoded" format:

Copy

1
2
access_token=SOME_ACCESS_TOKEN&expires_in=3600

To retrieve the " access_token " from this response body, you would use {{$Auth.Response.Body.access_token}}

EXAMPLE 2: response body in "application/json" format:

Copy

1
2
3
4
5
{
"access_token" : SOME_ACCESS_TOKEN,
"expires_in" : 3600
}

To retrieve the " access_token " from this response body, you would use {{$Auth.Response.Body.access_token}}

EXAMPLE 3: nested response body in "application/json" format:

Copy

1
2
3
4
5
6
7
8
{
"authz" : {
  "token" : SOME_TOKEN,
  "expires" : 140001230300
},
"apiKey" : SOME_KEY
}

To retrieve the value of " token " from this response body, you would use {{$Auth.Response.Body.authz.token}}