Authenticating your Request
Authentication Request
Authentication is completed via a POST request to the test URL shown below.
The Key below must always be stored securely. You can manage your keys if one is compromised.
The POST must contain the below data.
| Authentication Request | |||
|---|---|---|---|
| Field Name | State | Data Type | Description |
| merchantId | Mandatory | Integer | The Merchant ID provided to you during onboarding, or following the creation of your test account. This is NOT your 'mid', it is a value unique to axept® Cloud Connect. |
| keyId | Mandatory | Integer | This is the ID allocated to the merchant using the authentication key generation process. |
| key | Mandatory | String | This is the key / password generated using the authentication key generation process and associated with the Key ID. |
Authentication Response
A successful response will be 200 - OK and will contain the following two fields:
| Authentication Response | ||
|---|---|---|
| Field Name | Data Type | Description |
| Token | String | The JWT Bearer token. You should store or cache this to authenticate future requests. |
| ExpiresAt | String | The UTC Datetime that the Bearer Token will expire at |
Bearer Token Validity
Issued Bearer tokens are only valid for a given period, as indicated by the expiration date / time. Your POS system needs to manage when to request a bearer token. A new token should be requested in the following scenarios:
- Your POS system does not have a JWT bearer token e.g. the first request since start-up / reboot
- The JWT bearer token is due to expire or has already expired.
It is recommended that your POS system employs a thread-safe caching mechanism, which will auto-evict the cached bearer token. If the cache does not contain the bearer token when needed, it re-authenticates with axept® Connect Cloud and caches the issued bearer token. If the cache does contain the bearer token, it can be used for the subsequent authenticated operation.
Error Responses
| Error | Issue | Action |
|---|---|---|
400 | Bad Request | This represents a syntax error. Check the format of all fields and ensure they are correct then retry |
401 | Unathorized | The supplied data was formatted correctly but the supplied merchantId, keyId and key were not valid. Check your values and then retry. |
Example Code
Example Request
{
"merchantId": 12345,
"keyId": 12,
"key": "R2lJMTMzZ1RCVy60T1h4V3FNshy="
}
Example 200 Response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1bmlxdWVfbmFtZSI6IjEzMzI3IiwibmJmIjoxNjgxMTE2MTg5LCJleHAiOjE2ODExMTc5ODksImlhdCI6MTY4MTExNjE4OSwiaXNzIjoiaHR0cHM6Ly9vcHRvbWFueS1heGVwdGNvbm5lY3RjbG91ZG1lcmNoYW50LXBwZS5henVyZXdlYnNpdGVzLm5ldCIsImF1ZCI6ImF4ZXB0Q29ubmVjdENsb3VkLW1lcmNoYW50LWNsaWVudCJ9.WZddPEsxS7drQfvsvR0oGn5dity32_cYQ52aFjcDwTU",
"expiresAt": "2023-01-31T11:28:09Z"
}