# JWT Authentication

Annex Cloud Loyalty API Authentication Guide

Overview

Access to the Annex Cloud Loyalty APIs is secured using JSON Web Token (JWT) authentication to prevent unauthorized access. Each request sent to the platform must include a valid:

Authorization: Bearer <token> header in the HTTP request.

Failure to properly authenticate a request will result in the request being rejected by the server, and an error response will be returned. For every API request, the following process applies:

The request payload (or identifier for GET requests) must be Base64-encoded. An HMAC-SHA256 hash is generated from this encoded payload using a shared secret key (provided by Annex Cloud). This HMAC is embedded within a JWT payload. The JWT is signed using HS256 and sent with the request.

Step-by-Step Authentication Flow

1. Request Payload Handling


   POST Requests


- The raw JSON request body must be used exactly as sent (including character encoding).

- No JSON normalization or reordering should be performed.

- The body must be UTF-8 encoded and then Base64-encoded.


   GET Requests


- The request identifier (e.g., user_id) must be treated as a JSON string literal.

- The value must be wrapped in double quotes ("value").

- The quoted string must be UTF-8 encoded and then Base64-encoded.


2. HMAC Generation

- The Base64-encoded payload is hashed using HMAC-SHA256.

- The raw secret key must be used (do not Base64-encode the key).

- The resulting HMAC must be Base64-encoded.


   Formula: HMAC = Base64( HMAC-SHA256( Base64(payload), secret_key ) )


   This HMAC uniquely binds the JWT to the specific request content.



3. JWT Payload Structure


    The JWT payload contains standard claims along with the computed HMAC:


    Field	Description


- sub	Assigned site name

- exp	Expiration timestamp (Unix time in seconds)

- site_id	Assigned site identifier

- hmac	Base64-encoded HMAC of the request payload


       Example:


              {


                "sub": "SITE_NAME",


                "exp": 1700000000,


                "site_id": 12345678,


                "hmac": "q8P1ZtRk8fPZ5ZyM..."


              }



4. JWT Construction and Signing


          JWT Header:

          
          {


            "alg": "HS256",


            "typ": "JWT"


          }


- The header and payload must be Base64URL-encoded.

- The token must be signed using HMAC-SHA256 with the same secret key.

- Final token format: Base64Url(header).Base64Url(payload).Base64Url(signature)


5. Sending the Token


    The JWT must be included in the HTTP header:


- Authorization: Bearer <JWT_TOKEN>



    Each request requires a newly generated token, as the HMAC is tied to the specific request payload.

    
    Important Notes


- UTF-8 encoding must be preserved, especially for non-ASCII characters (e.g., accented characters).

- POST payloads must not be reformatted or re-serialized after signing.

- GET request parameters must be wrapped in double quotes before hashing.

- Tokens expire and must be regenerated for each request.



    For further assistance, please contact your Annex Cloud Customer Enablement Manager or Customer Success Manager.