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.
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.
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