Data source Merge API Reference

When configuring Skuid data sources and authentication providers, additional merge variables are added to the Merge API that allow you to access information about the data source’s authentication configuration and current state.

There are a number of places in data source and authentication provider configuration that process Skuid’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 data source’s configured Credential Source policy.

Example: Data source Credential Source = “Shared: Org-wide”.

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

Example: Data source Credential Source = “Per-User, with optional Profile / Org-wide Defaults”.

If the running user has entered their own username / password for a given data source, then {{$Auth.Username}} will resolve to the user’s username. However, if the running user has NOT entered credentials, then Skuid 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 data source’s configured Credential Source policy. For instance, if the data source’s Credential Source is Shared: Org-wide, this will retrieve the Org-Wide default Username defined on the data source.

$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

image0

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

This merge is mainly useful for data sources that use the “Separate Authentication URL” or “Authentication Provider” authentication methods.

EXAMPLE

  1. 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.
  2. To get Skuid 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 data source. Useful for retrieving access tokens returned after successful authentication attempts.

This merge is mainly useful for data sources that use the “Separate Authentication URL” or “Authentication Provider” authentication methods.

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

1
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:

1
2
3
4
{
"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:

1
2
3
4
5
6
7
{
"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}}