Authentication Workflow

This page explains how the authentication takes place to get started with the APIs.

Authentication is the most important part of the API integration as there can be many complications while doing the authorization. The clients must obtain a JWT token and send the token with all the requests. This enables individual services to verify the user has been authenticated.

How to get started

1. Terms & Conditions and Register User

2. Update User Information

3. Get Access Token and verify user information

4. Bind Device to account

1. Terms & Conditions and Register User

At first, you have to get the configuration data for example the terms and conditions link, privacy policy links, etc. To get this information, make a GET request to /v1/configuration and from the response body, you will be able to see the data that includes the ones mentioned above. A sample response body is given below:

[
    {
        "configurationKey": "SHARE_ACCOUNT",
        "configurationValue": "ENABLED"
    },
    {
        "configurationKey": "NEW_ACCOUNT",
        "configurationValue": "ENABLED"
    },
    {
        "configurationKey": "SLIPS",
        "configurationValue": "ENABLED"
    },
    {
        "configurationKey": "ADD_CARD_VIRTUAL_CARD_LIMIT",
        "configurationValue": "3"
    },
    {
        "configurationKey": "ADD_CARD_CARD_LIMIT",
        "configurationValue": "3"
    },
    {
        "configurationKey": "EXTERNAL_ACCOUNTS",
        "configurationValue": "OFF"
    },
    {
        "configurationKey": "CURRENCY_EUR",
        "configurationValue": "ENABLED"
    },
    {
        "configurationKey": "TRAVEL_PACK",
        "configurationValue": "OFF"
    },
    {
        "configurationKey": "AAZZUR_WEBSITE",
        "configurationValue": "https://www.aazzur.com/"
    },
    {
        "configurationKey": "AAZZUR_CONTACT",
        "configurationValue": "[phone]"
    },
    {
        "configurationKey": "SPLIT_BILL",
        "configurationValue": "ENABLED"
    },
    {
        "configurationKey": "SIGNUP",
        "configurationValue": "ENABLED"
    },
    {
        "configurationKey": "ADD_CARD_PHYSICAL_CARD_LIMIT",
        "configurationValue": "3"
    },
    {
        "configurationKey": "CARDS_TNC",
        "configurationValue": "https://www.aazzur.com/consumer-cardholder-terms/"
    },
    {
        "configurationKey": "AAZZUR_HELP_CENTER",
        "configurationValue": "https://www.aazzur.com/aazzur-faq/"
    },
    {
        "configurationKey": "ADD_CARD",
        "configurationValue": "ENABLED"
    },
    {
        "configurationKey": "CURRENCY_GBP",
        "configurationValue": "OFF"
    },
    {
        "configurationKey": "SEPA_ADDRESS",
        "configurationValue": "OFF"
    },
    {
        "configurationKey": "AAZZUR_TNC",
        "configurationValue": "https://www.aazzur.com/terms-and-conditions/"
    },
    {
        "configurationKey": "AAZZUR_PRIVACY_POLICY",
        "configurationValue": "https://www.aazzur.com/aazzur-privacy-policy/"
    },
    {
        "configurationKey": "NEW_ACCOUNT_ACCOUNT_LIMIT",
        "configurationValue": "5"
    }
]

To create a user with the v1/customers/me endpoint by providing customer information such as email, password, identity like first name, last name, etc. The createCustomer endpoint is given below:

createCustomer

POST//customers:8080/v1/customers

Header parameters

Body

application/json

body

email*string

passportInfoPassportInfo

password*string

consentsarray of Consent

languagestring

Response

201202401403404

Created

Request

JavaScriptCurl

const response = await fetch('//customers:8080/v1/customers', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "email": "text",
      "password": "text"
    }),
});
const data = await response.json();

A sample JSON request body is given below as well. Have a look at the consent object, there are terms and conditions that you will have to show to the users that they have read it and there can be a checkbox or a button to take their consent that they have agreed to all the terms and conditions.

{
  "email": "[e-mail]",
  "password": "1234",
  "language": "en-US",
  "consents": [
    {
      "accepted": true,
      "type": "CARD_TERMS_AND_CONDITIONS"
    },
    {
      "accepted": true,
      "type": "PRIVACY_POLICY"
    },
    {
      "accepted": true,
      "type": "TERMS_AND_CONDITIONS"
    },
    {
      "accepted": true,
      "type": "PRODUCT_UPDATES"
    },
    {
      "accepted": true,
      "type": "NEWSLETTER"
    }
   ],
  "passportInfo":{
    "firstName": "John",
    "lastName": "Doe",
    "title": "Mr"
  }
}

2. Update User Information

After creating the user with the previous endpoint, you will have to update the user information with additional information such as Passport info, KYC info, address, phone number, updated consent, etc. To be able to get the access token to use the other APIs, the user has to be a valid user with all the information mentioned and the document numbers which are entered have to be verified. If the user is not valid then the user would not be able to get the OAuth token resulting in not being able to use the other API endpoints to do transactions or other things.

A sample request body is given below for understanding the request.

updateCustomer

Required scopes - signup

PATCH//customers:8080/v1/customers/me

Body

application/json

body

phoneNumberstring

addressAddress

passportInfoPassportInfo

Response

202204401403

Accepted

Body

*/*

statusstring

Request

JavaScriptCurl

const response = await fetch('//customers:8080/v1/customers/me', {
    method: 'PATCH',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

Response

{
  "status": "text"
}

Sample Request Body

{
    "phoneNumber": "[phone]",
    "passportInfo": {
        "nationality":"ABC",
        "dateOfBirth":"1900-01-01",
        "gender":"MALE"
    },
    "address" : {
        "addressLine1":"XX XXXXXX Road",
        "city":"XXXXX",
        "country":"XXX",
        "postalCode":"XXX XXX"
    }
}

From the previous request, you will have the customer's phone number and the email address that needs to be verified. There are two different endpoints that need to be used to verify them mentioned below. Please do remember that to use these two APIs you will need to use the OAuth Access Token.

3. Get Access Token and Verify User Information

curl localhost:8080/sessions/oauth/token -u [e-mail]:pass -d grant_type=password -d username=[e-mail] -d password=pass

where:

• /sessions/oauth/token - sessions is a name of service performing authentication/authorization and /oauth/token is a token endpoint per OAuth2 specification

• -u [e-mail]:pass is username:password for basic authentication

• -d grant_type=password is a requested authentication flow

• -d username and password are username and password once again required for OAuth authorization

The access token will be valid for 30 minutes. It is not possible to extend its duration, after it is expired user should be asked to enter his credentials to obtain the token again.

The result of the request will provide the access token similar to the JSON response added below:

{
    "access_token": "SAMPLE ACCESS TOKEN",
    "token_type": "bearer",
    "expires_in": 1799,
    "scope": "signup",
    "clientId": "app",
    "anyDeviceUser": false,
    "customerId": "SAMPLE CUSTOMER ID",
    "userType": "CUSTOMER",
    "userId": "SAMPLE USER ID",
    "programme": "AAZZUR",
    "username": "[e-mail]",
    "jti": "*********"
}

After getting the access token from the response body, you will have to reuse the access token while sending the email verification and phone verification API request. Keep in mind that you will have to send the oauth token found in the previous request in the later ones as a bearer token. The email verification request API and the phone verification API requests are added below:

requestEmailVerification

Required scopes - signup

POST//customers:8080/v1/customers/me/email-verification-request

Response

201202401403404

Created

Request

JavaScriptCurl

const response = await fetch('//customers:8080/v1/customers/me/email-verification-request', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

sendVerificationToken

Required scopes - signup

POST//customers:8080/v1/customers/me/phone-verification-request

Response

201202401403404

Created

Request

JavaScriptCurl

const response = await fetch('//customers:8080/v1/customers/me/phone-verification-request', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

The above request will send a confirmation email and an OTP to the user's phone number. You will have to verify if the user actually enters the correct OTP with another API that is mentioned below. The following API requires the code in the request body.

verifyCode

POST//sessions:8080/sessions/phone-verification-tokens

Body

application/json

body

code*integer (int32)

Response

200201401403404

OK

Request

JavaScriptCurl

const response = await fetch('//sessions:8080/sessions/phone-verification-tokens', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({}),
});
const data = await response.json();

verifyToken

POST//sessions:8080/sessions/email-verification-tokens

Body

application/json

body

token*string

Response

200201401403404

OK

Request

JavaScriptCurl

const response = await fetch('//sessions:8080/sessions/email-verification-tokens', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "token": "text"
    }),
});
const data = await response.json();

4. Bind Device to Account

Client devices are always bound when they are done with the signup process and when another device tries to log in with the same credentials, it is blocked as the signing credentials are different. The binding process is done with a private-public RSA keypair that is generated from the device that they log in to.

An RSA key pair includes a private and a public key. The RSA private key is used to generate digital signatures, and the RSA public key is used to verify digital signatures. The RSA public key is also used for key encryption of DES or AES DATA keys and the RSA private key for key recovery.

To bind the device, we have to call the device binding API endpoint which requires the public key, device name, and the OTP for confirming the device identity. A sample JSON response body is given below:

{
        "deviceName": data.deviceName,
        "code": data.smsCode,
        "publicKey": data.publicKey
}

The device binding API endpoint is the one mentioned below:

registerDevice

Required scopes - signup

POST//customers:8080/v1/devices

Body

application/json

request

code*integer (int32)

deviceNamestring

publicKey*string

Response

201202401403404

Created

Request

JavaScriptCurl

const response = await fetch('//customers:8080/v1/devices', {
    method: 'POST',
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "publicKey": "text"
    }),
});
const data = await response.json();

You can get the OTP code by sending a POST request to the below API:

sendVerificationToken

Required scopes - signup

POST//customers:8080/v1/customers/me/phone-verification-request

Response

201202401403404

Created

Request

JavaScriptCurl

const response = await fetch('//customers:8080/v1/customers/me/phone-verification-request', {
    method: 'POST',
    headers: {},
});
const data = await response.json();

Please do remember that you will have to add the headers as well which are mentioned below:

{
      "Authorization": "Bearer " + accessToken!,
      "Content-Type": "application/json",
      "X-Request-ID": Uuid().v4().toString(),
      "X-AAZZUR-CLIENT-ID": AppConfig.clientID
}

On the first object on the header, the access token is used which is received from the /sessions/oauth/token endpoint mentioned at the top of the page.