Client APIs

# Authentication and authorization

To ensure the authentication and authorization of client transactions on the UNIQREWARDS Client API v3, OAuth 2.0 (opens new window) is implemented as the standard for REST APIs.

The client credentials (opens new window) [RFC] (opens new window) grant flow is used by this API and the issued tokens are JWT (opens new window), carrying the authorizations granted after authentication.

In this documentation, we use auth as shorthand for both authentication and authorization. Authentication is the verification of the client identity while authorization represents the permissions granted to the client.

# Overview

The UNIQREWARDS Client API v3 auth is a two-step process from the client's perspective.

First, an auth token is requested using a pair of credentials. This is the client authentication. The issued JWT token returned is valid for a period of time (usually 1 hour) and contains the authorizations to access the API resources.

The second step involves attaching the auth token obtained in the first step to all requests performed on the API. If the token is valid and the authorization sufficient, the requested resources are made available.

# Credentials

A pair of credentials, consisting of an id/secret, will be provided to each client for interaction with the UNIQREWARDS Client API v3.

Each environment requires a separate pair of credentials.

  • client_id: a unique string identifying the API client (a UNIQGIFT client with Client API v3 access).
  • client_secret: a server-generated string that must be kept secret and secured, used to authenticate the client with the auth service.

Warning

Clients are responsible for maintaining the security of the client_secret. Adhering to best security practices is essential. These practices include avoiding hardcoding the secret in application code, ensuring secure storage, and ensuring that only backend systems can access and utilize the secret.

# Auth token

Completing the OAuth 2.0 client credentials authentication flow , the auth service issues an access token. It is referred to as the auth token in this documentation.

The auth token is of JWT (opens new window) type. In short, a JWT token is composed of 3 parts separated by dots: header . payload . signature

Both the header and the payload are base64 JSON encoded strings that can be decoded and read.

The header section contains the cryptographic key identifier and the algorithm used to allow verification of the token and its signature.

The payload has 3 key information for the API:

  • client_id: unique client identifier corresponding to the credentials ID. This is the authentication information.
  • exp for expiration: a UNIX timestamp (opens new window) after which the token is expired.
  • scope: a space-separated list of authorizations the client has been granted. See the scope section for the list of authorizations that can be requested and granted.

The signature section contains an integrity signature that is verified by the API to ensure the token wasn’t tempered with.

Warning

Auth tokens are sensitive information that authenticate the client. They must be handled by backend systems only.

Note

Client can store and reuse auth tokens during their validity period (1 hour) to save the time to issue a new one each request.

# Scopes

As mentioned in the auth token section, scopes are authorizations to access API resources.

When requesting an auth token, required scopes should be specified. it is good practice to request a token with as few scopes as required by the intended use of the API.

Each scope has two parts, one specific to the API and environment and one corresponding to the permission requested.

The scope format is api _ version (_ environment) / permission.

Below is a table of available scopes that can be requested, along with their descriptions and applicability across different environments:

Permission Description DEMO UAT PRODUCTION
issue_vouchers Permission to issue new vouchers client_v3_demo/issue_vouchers client_v3_uat/issue_vouchers client_v3/issue_vouchers
read_vouchers Access issued voucher details and status client_v3_demo/read_vouchers client_v3_uat/read_vouchers client_v3/read_vouchers
read_catalogue Access product details and catalogue of products client_v3_demo/read_catalogue client_v3_uat/read_catalogue client_v3/read_catalogue

# Auth service resources

Here are the auth services URLs to use based on the environment:

Environment Auth service URL
DEMO https://uniqgift-qa.auth.ap-southeast-1.amazoncognito.com/oauth2/token
UAT https://uniqgift-qa.auth.ap-southeast-1.amazoncognito.com/oauth2/token
PRODUCTION https://uniqgift.auth.ap-southeast-1.amazoncognito.com/oauth2/token

# Obtain an auth token

This section takes the example of requesting an auth token for the DEMO environment to issue new vouchers and access the product catalogue.

Warning

ID and secret in the example are not valid credentials, they can't be used to authenticate. The signature of token is also invalid as it was tempered with for the documentation purpose.

# Auth request

ID and secret are provided in the Authorization header using basic authentication (opens new window) (base64 encoding of ID and secret).

POST https://uniqgift-qa.auth.ap-southeast-1.amazoncognito.com/oauth2/token

Request headers:
Authorization: Basic eWpkanl0YzV6d3kzb3RhM3l6ZTJuZ3kwbmo6bWR1MG5keTFuZGF6bWRqanl0cTR6anUxbWprMW90dXhvd25obXR6anp3aWdpYzBreXpk
Content-Type: application/x-www-form-urlencoded

Request body formatted from application/x-www-form-urlencoded:
grant_type: "client_credentials"
scope: "client_v3_demo/issue_vouchers client_v3_demo/read_catalogue"

# Auth response

If the credentials are valid and the requested scopes available to the client, the auth service will return the auth token in the response body as access_token.

HTTP/1.1 200 OK

Content-Type: application/json; charset=UTF-8

 




{
    "access_token": "eyJraWQiOiJ3XC9TMTNMZXY0dkRhZDFhTHZPSDF5M0xzQmNhd1lTc3c0SjlQeGorczNuYz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ5amRqeXRjNXp3eTNvdGEzeXplMm5neTBuaiIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiY2xpZW50X3YzX2RlbW9cL2lzc3VlX3ZvdWNoZXJzIGNsaWVudF92M19kZW1vXC9yZWFkX2NhdGFsb2d1ZSIsImF1dGhfdGltZSI6MTcwNDA3MDgwMCwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLmFwLXNvdXRoZWFzdC0xLmFtYXpvbmF3cy5jb21cL2FwLXNvdXRoZWFzdC0xX1pQQm8xRGZFVCIsImV4cCI6MTcwNDA3NDQwMCwiaWF0IjoxNzA0MDcwODAwLCJ2ZXJzaW9uIjoyLCJqdGkiOiIwYzJjYjIxNC1kOTdjLTQ5NDUtYTc2MS1lZWYzZjJlZDA1ZTEiLCJjbGllbnRfaWQiOiJ5amRqeXRjNXp3eTNvdGEzeXplMm5neTBuaiJ9.lT1Y_nCdCKrYGfK-booBRllLnpb3ekQ0k-nQ6GIWwZrjK6j9pZ9hCn_dbft8u5cGYnxWC4LypE7uNnq329PxXCFVj2YDXt_6i0IR6awTsvimA3wFqt0rb2pVdXKbB2LuP42CiW1NH8kM2_F456_UtYCG5dVbxnANypbdQq4kHEg29HrPuTqtbW6sqXT6b7Xobs2Rjop9AfLSufIGkRuIxKi9MOpkEnZGAhN0zAyOS2eXTFg0QuOIvlL4mwDtDMlIdbHw2NZ0M75rNQa-nzBueg8fcgECNegbJ6_67N26mj3Xbl5k07iMTvs2FQ4VbuvocwS1B5gqJYT9rFxpZOC1mw",
    "expires_in": 3600,
    "token_type": "Bearer"
}

Base64 decoding the payload part of the auth token is providing the scope, expiration timestamp and client ID:




 


 



 


{
  "sub": "yjdjytc5zwy3ota3yze2ngy0nj",
  "token_use": "access",
  "scope": "client_v3_demo/issue_vouchers client_v3_demo/read_catalogue",
  "auth_time": 1704070800,
  "iss": "https://cognito-idp.ap-southeast-1.amazonaws.com/ap-southeast-1_ZPBo1DfET",
  "exp": 1704074400,
  "iat": 1704070800,
  "version": 2,
  "jti": "0c2cb214-d97c-4945-a761-eef3f2ed05e1",
  "client_id": "yjdjytc5zwy3ota3yze2ngy0nj"
}

# Use the auth token

To use the auth token for requests on the API, attach the issued token using the Authorization header with bearer (opens new window) authentication scheme.


 

Request header:
Authorization: Bearer eyJraWQiOiJ3XC9TMTNMZXY0dkRhZDFhTHZPSDF5M0xzQmNhd1lTc3c0SjlQeGorczNuYz0iLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ5amRqeXRjNXp3eTNvdGEzeXplMm5neTBuaiIsInRva2VuX3VzZSI6ImFjY2VzcyIsInNjb3BlIjoiY2xpZW50X3YzX2RlbW9cL2lzc3VlX3ZvdWNoZXJzIGNsaWVudF92M19kZW1vXC9yZWFkX2NhdGFsb2d1ZSIsImF1dGhfdGltZSI6MTcwNDA3MDgwMCwiaXNzIjoiaHR0cHM6XC9cL2NvZ25pdG8taWRwLmFwLXNvdXRoZWFzdC0xLmFtYXpvbmF3cy5jb21cL2FwLXNvdXRoZWFzdC0xX1pQQm8xRGZFVCIsImV4cCI6MTcwNDA3NDQwMCwiaWF0IjoxNzA0MDcwODAwLCJ2ZXJzaW9uIjoyLCJqdGkiOiIwYzJjYjIxNC1kOTdjLTQ5NDUtYTc2MS1lZWYzZjJlZDA1ZTEiLCJjbGllbnRfaWQiOiJ5amRqeXRjNXp3eTNvdGEzeXplMm5neTBuaiJ9.lT1Y_nCdCKrYGfK-booBRllLnpb3ekQ0k-nQ6GIWwZrjK6j9pZ9hCn_dbft8u5cGYnxWC4LypE7uNnq329PxXCFVj2YDXt_6i0IR6awTsvimA3wFqt0rb2pVdXKbB2LuP42CiW1NH8kM2_F456_UtYCG5dVbxnANypbdQq4kHEg29HrPuTqtbW6sqXT6b7Xobs2Rjop9AfLSufIGkRuIxKi9MOpkEnZGAhN0zAyOS2eXTFg0QuOIvlL4mwDtDMlIdbHw2NZ0M75rNQa-nzBueg8fcgECNegbJ6_67N26mj3Xbl5k07iMTvs2FQ4VbuvocwS1B5gqJYT9rFxpZOC1mw

← Request ID →