OAuth JWT Bearer Authentication

Available to Private Apps only. Used when there is no third party involved for service calls or on behalf of the user/account who created the App.

This is a more secure process to that of the Client Credentials process and requires an OAuth 2 Server Key. Your application calls the Evance API on behalf of your account rather than on behalf of a user. 

Overview

To support JWT Bearer Authentication, first create an OAuth 2 Server Key within your API control panel. 

Then, your application prepares to make authorised API calls by using the Server Key credentials to request an access token from the OAuth 2 authentication server. 

Finally, your application may use the access token to call Evance APIs.

Creating a Server Key

After adding a Private App to your API console you will need to do the following:

{
    "account": "example.evance.me",
    "client_id": "2b4ec2959c42e02089abbf8069c53956.2.app.evance.me",
    "private_key": "d92b988985628fdd9ebdd71607d7890a01185671bb98e89f39421b88cf93c33c",
    "algorithm": "HS256"
}

Creating the JWT Bearer

A JWT is composed of three dot separated parts: a header, a claim set, and a signature. The header and claim set are JSON objects serialized to UTF-8 bytes, then encoded using the Base64url encoding.

{Base64url encoded header}.{Base64url encoded claim set}.{Base64url encoded signature}

The JWT header

The header consists of two fields: the signing algorithm (defined in your credentials) and the format of the assertion.

{"alg":"HS256","typ":"JWT"}

The Base64url representation of this looks like this:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9

The JWT claim set

The JWT claim set includes the permissions being requested (scopes), the target of the token, the issuer, the time the token was issued, and the lifetime of the token. Most of the fields are mandatory. Like the JWT header, the JWT claim set is a JSON object and is used in the calculation of the signature.

The required properties of the claim set are as follows:

An example of the JSON representation of these properties:

{
    "iss": "2b4ec2959c42e02089abbf8069c53956.2.app.evance.me",
    "scope": "account.readonly",
    "aud": "https://example.evance.me/oauth/token",
    "exp": 1487843714,
    "iat": 1487840114
}

The JSON claim set should then be serialized to a UTF-8 and Base64url-safe encoded string. For example:

ewogICAgImlzcyI6ICIyYjRlYzI5NTljNDJlMDIwODlhYmJmODA2OWM1Mzk1Ni4yLmFwcC5ldmFuY2UubWUiLAogICAgInNjb3BlIjogImFjY291bnQucmVhZG9ubHkiLAogICAgImF1ZCI6ICJodHRwczovL2V4YW1wbGUuZXZhbmNlLm1lL29hdXRoL3Rva2VuIiwKICAgICJleHAiOiAxNDg3ODQzNzE0LAogICAgImlhdCI6IDE0ODc4NDAxMTQKfQ

The JWT signature

The JWT is calculated using the correct signing algorithm defined in the alg property of the JWT header. The input for the signature is as follows:

{Base64url encoded header}.{Base64url encoded claim set}

For example:

eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.ewogICAgImlzcyI6ICIyYjRlYzI5NTljNDJlMDIwODlhYmJmODA2OWM1Mzk1Ni4yLmFwcC5ldmFuY2UubWUiLAogICAgInNjb3BlIjogImFjY291bnQucmVhZG9ubHkiLAogICAgImF1ZCI6ICJodHRwczovL2V4YW1wbGUuZXZhbmNlLm1lL29hdXRoL3Rva2VuIiwKICAgICJleHAiOiAxNDg3ODQzNzE0LAogICAgImlhdCI6IDE0ODc4NDAxMTQKfQ

Please check the correct encoding algorithm to use below (based on the algorithm in your server key JSON file). 

Note: Evance currently defaults credentials for signing with HS256 only.

The signature must then be Base64url encoded. The header, claim set, and signature are concatenated together with a period ( .) character. The result is a JWT ready for transmission.

Making the access token request

Having generated the signed JWT, your application can use it to request an access token. The access token request is an HTTPS POSTrequest, and the body is URL encoded. The URL is as defined in the aud property of your claim set (e.g. https://example.evance.me/oauth/token).

The following parameters are required in the HTTPS POST request:

POST /admin/oauth/token.json HTTP/1.1
Host: [account].evance.me
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-bearer
&assertion=eyJ0eXAiOiJKV1QiL[...omiited for brevity...]AxMTQKfQ

Access token

A successful request will receive a JSON response from the server similar to the following:

{
    "access_token": "43e213757dd5a224ace6ffc22b8c436219c5830b",
    "expires_in": 3600,
    "token_type": "Bearer",
    "scope": null
}

You now have an access_token with a 1 hour lifespan, with which to make further requests to the Evance API. When your access_token expires you will need to repeat this process to gain further API access.