Authentication

This API uses OAuth2 authentication using the client credentials grant type. Credentials are obtained by registering with Elavon as an API partner. Once registered, these credentials will be issued:

Name	Value	Description
Consumer Key	string	Unique client identifier (username). This value is used in the Authorisation header in Authentication request.
Consumer Secret	string	Unique client secret (password). This value is used in the Authorisation header in Authentication request.

Partners have to adhere to two-way authentication patterns called Mutual Transport Layer Security (mTLS).

Two-way authentication is a process that requires the partner and Elavon to exchange digital certificates from a mutually trusted certificate authority (CA) to authenticate each other’s identity.

Both the partner and Elavon must be registered with a certificate authority (CA), and configured locally as a trusted party. This security measure reduces the risk of unauthorised use of credentials.

For more information, see the Mutual Transport Layer Security (mTLS) Guide.

Note: Keep your API keys secure! Do not share them publicly (code repository or client-side code).

Important: If your API keys are compromised, contact Elavon Partner Support immediately to reissue credentials.

OAuth - Authorisation Client Credential Grant Flow

The server determines the partner/data aggregator. A token is received after the authentication request is sent. From there, APIs can be accessed by this token. This process is depicted in the following authentication workflow diagram.

Partner/Data Aggregator

Request Authorisation

POST

/auth/oauth2/v1/token

Authorisation Request Body

The credentials are supplied in request header:

Field	Type	Description
Authorization	string	A base64 encoded string consisting of the Consumer Key and Consumer Secret values separated by a colon :.
Content-Type	“application/x-www-form-urlencoded”	Content-Type for the post request.
Correlation-ID	Any alphanumerical value	(Optional) Unique id for every request response pair.
grant_type (Body Parameter Name)	client_credentials	Required OAuth 2.0 grant type.

Sample Request

POST
/auth/oauth2/v1/token HTTP/1.1

Accept: application/json Authorization: Basic WkNHWWNDcGtNRFJFSnJTYjB4WHE3dlBJUEhnU1h2S0E6ZjNJbFZpTFBZOGpHbWZsVw== Content-Type: application/x-www-form-urlencoded Correlation-Id: 3c49b65a-bdad-481d-b4f8-e69d067d42e8 Content-Length: 29 grant_type=client_credentials

Response

A successful response contains the JSON body values below. The accessToken value must be saved for use in subsequent requests as the Authorisation header value, and expires in expiresIn seconds.

Authorisation Response Structure

A successful response contains the body values below. The accessToken value should be saved for use in subsequent requests, and expires in expiresIn seconds.

Field	Type	Description
tokenType	“BearerToken”	As specified by OAuth.
accessToken	string	The Bearer access token to be used as the Authorisation header value in subsequent requests.
expiresIn	number	Number of seconds until token expires.

Sample Response

HTTP/1.1 200 OK

Date: Mon, 30 Mar 2020 19:17:25 GMT
Content-Type: application/json
Content-Length: 159
Correlation-Id: 3c49b65a-bdad-481d-b4f8-e69d067d42e8
{
    "tokenType": "BearerToken",
    "expiresIn": "899",
    "accessToken": "yKQyX41TbOeIAxXO0PLoP47Xma6y"
}

Subsequent API Request Example

Subsequent API requests must include the accessToken value as the Bearer token in the Authorisation header.

POST
/example/url

Accept: application/json
Authorization: Bearer EwxKaEeHibaLGRa2cY2DUtcuYDntg8
Content-Type: application/json