Authentication Mappings#

Auth mappings tell us how to interpret the credentials or tokens your user provides, as usable Basic Auth, Digest Auth, HTTP headers and query strings. Let's use an example where there are two auth fields available to us: account_name and api_key.

Basic Auth#

Your app might use api_key as the username and password is ignored:

{
  "username": "{{api_key}}",
  "password": "x"
}

Or maybe, where account_name is the username and api_key is the password:

{
  "username": "{{account_name}}",
  "password": "{{api_key}}"
}

In any case, the Auth Mapping should provide a username and password field, which we will use to generate an header like:

Authorization: Basic WkFQSUVSIExPVkVTIFlPVTpYT1hP

This will be added to all prepared requests to your server.

Digest Auth#

Your app might have account_name as the username and api_key as the password:

{
  "username": "{{account_name}}",
  "password": "{{api_key}}"
}

This will produce an header similar to Digest Auth, but using a server provided nonce. We handle the computation of the response, so you don't have to think about realms, nonces, or qop's.

API Key (Query String)#

Your app might expect the API key as secret parameter in the query string:

{
  "secret": "{{api_key}}"
}

Which will append ?secret=0123456789 to the end of all URLs.

API Key (Headers)#

Say your app expects two headers called X-Account-Name and X-API-Key:

{
  "X-Account-Name": "{{account_name}}",
  "X-API-Key": "{{api_key}}"
}

This will add headers like:

X-Account-Name: myfancyaccount
X-API-Key: 0123456789

Session Auth#

With Session Auth, you can map the Authentication Fields as well as what is returned by your get_session_info() scripting method. In most cases, this method will return a token and this is the only value your API needs for further requests.

Let's say our method makes a request which sends our account_name and api_key and receives the following object:

{
  token: "WkFQSUVSIExPVkVTIFlPVTpYT1hP",
  name: "John Doe"
}

If your app expects to receive the token in an header named X-Token the auth mapping could be:

{
  "X-Token": "{{token}}"
}

And we would set Auth Placement to Header:

This will add a header like:

X-Token: WkFQSUVSIExPVkVTIFlPVTpYT1hP

If your app expects the token as Query String parameter, select Querystring for Auth Placement instead.

↑ Was this documentation useful? Yes No
Get Help