Authentication

The Conferma API enforces HTTP Bearer Authentication on incoming requests. This method requires the standard Authorization header to be provided containing an access token that has been obtained from an authentication end-point.

This sample request uses a bearer token to list payments:

cURL

curl --request GET \
  --url https://api.cert-confermapay.com/deployments/v1/deployments \
  --header 'Authorization: Bearer <access_token>'

Obtaining an Access Token

You must request an access token from the Conferma authorisation server, which utilises the Oauth 2.0 schema.

When you create an application to use the Conferma API, you will be given client credentials for your app.

To get an access token using the client credentials grant type, pass your provided platform credentials in the get access token call. In response, the authorisation server will issue an access token.

Re-use the access token until it expires. When it expires, provide your credentials again to get a new token.

Required Credentials:

• grant_type—The grant type. Set to client_credentials.
• client_id—Your client id.
• client_secret—Your client secret.
• scope—Your platform key name -pkn- unique to the client platform application.

The client_id and client_secret should be combined and Base64 encoded as part of Basic authentication.

Follow these steps to produce the encoded_credentials:

Text

<encoded_credentials> = Base64(<client_id>:<client_secret>)

Include this encoded_credentials in the Authorization header with the Basic authentication scheme.

cURL

curl --request POST \
--url  https://assure.cert-confermapay.com/token \ 
--header "Content-Type: application/x-www-form-urlencoded" \ 
--header 'Authorization: Basic <encoded_credentials>' \
--data "grant_type=client_credentials&scope=<pkn>"

Ensure that grant_type is set to client_credentials.

An access_token will be provided in the response, together with the expires property that will allow you to manage the token.

JSON

{
    "access_token": "<access_token>",
    "expires": "2019-11-08T11:01:45.6475887+00:00",
    "issued": "2019-11-08T10:56:45.6475887+00:00"
}

Token Expiration

Access tokens have a finite lifetime. The expires_in field in the get access token response shows the time of expiry for the access token.

To detect when an access token expires, write code to either:

• Keep track of the expires value in the token response. The value is expressed as a DateTime.
• Handle the HTTP 401 Unauthorised status code. The API endpoint issues this status code when it detects an expired token.

Do not create another access token before the one you have expires. Creating a new token will revoke any other active token for your platform.