Introduction

This document provides a comprehensive guide for implementing Client Access Token authentication using JSON Web Tokens (JWT) when integrating with Annex Cloud's public APIs.

To ensure data integrity and request validation, the token must include a signed hmac (Hash-based Message Authentication Code) generated using the request payload or parameters and a shared secret. This hmac is a key element in preventing tampering and unauthorized access.

This guide covers:

• The structure of a JWT token
• Step-by-step instructions for generating the token
• HMAC generation for POST, PATCH, and GET requests
• PHP code samples for token creation
• Required headers to authenticate API calls

Following these instructions will help you securely interact with the API using a stateless and standardized authentication process.

Structure and Generation of a JWT Token

A JSON Web Token (JWT) is a compact, secure token format used for authenticating API requests. It consists of three Base64URL-encoded parts, separated by periods (.) as shown below:

<base64url-encoded header>.<base64url-encoded payload>.<signature>

Components of a JWT Token

1. Header
Contains metadata about the type of token and algorithm used.

2. Payload
 Contains the claims or actual data being transmitted. Required fields:

• sub
  • Data Type: String
  • Description: Identifier for the client company, as agreed during the integration discussion.

NOTE: This can be any string value - it does not affect the execution result.

• exp
  • Data Type: Number or String
  • Description: Token expiration time in UTC, represented as a Unix timestamp (in seconds).

              Example: 2019/09/16 22:50:28 → 1568674228

• site_id
  • Data Type: String
  • Description: The Annex Cloud site ID assigned to your organization.
• hmac
  • Data Type: String
  • Description: A Base64-encoded HMAC-SHA256 signature generated using a shared secret. This value ensures the integrity of the request.
  • The input for HMAC generation depends on the API type:
    • For POST/PATCH requests: Use the request payload (in JSON format)
    • For GET requests: Use the query parameter(s)

NOTE: Ensure all non-ASCII characters in the input are escaped before generating the HMAC. Mismatches will result in authentication failure.

Example of a payload

{
  "sub": "<client_company_name>",
  "exp": 1568674228,
  "site_id": "<your_site_id>",
  "hmac": "<generated_hmac>"
}

3. Signature
 Created by signing the encoded header and payload with the shared secret using HMACSHA256:

The final token structure:

base64urlencoded (JWT_Header). base64urlencoded (JWT_Payload). JWT_Signature

Steps to Generate the JWT Token

Step 1: Prepare the Payload

Include the following required fields:

• sub
• exp
• site_id
• hmac (see next section for how to generate it)

Step 2: Encode Header and Payload

• Convert both header and payload to JSON
• Base64URL encode each

Step 3: Generate the Signature

• Concatenate the encoded header and payload with a period (.)
• Sign this string using HMACSHA256 with the shared secret

Step 4: Combine All Parts

• Final JWT:

       base64url(header) + "." + base64url(payload) + "." + signature 

Use this JWT as a bearer token in your API requests.

HMAC Generation for POST, PATCH, and GET Requests

For POST/PATCH Requests

• Use the raw request payload for HMAC generation.

Steps:

1. Convert payload to JSON.
2. Escape non-ASCII characters using json_encode (PHP).
3. Base64 encode the JSON string.
4. Generate HMAC using SHA256 and your shared secret.
5. Base64 encode the resulting HMAC.

NOTE: The request payload sent in the API call must exactly match the payload used for HMAC generation.

For GET Requests

• Use the query parameter (usually a single value) for HMAC.

Steps:

1. Convert the parameter to JSON.
2. Escape characters using json_encode.
3. Base64 encode the JSON string.
4. Generate HMAC using SHA256 and your shared secret.
5. Base64 encode the resulting HMAC.

NOTE: Any mismatch will result in a 401 Unauthorized error.

PHP Code Samples for Token and HMAC Creation

POST/PATCH Request Example

// Sample payload
$payload = [     
    "id" => "2",
    "email" => "abrar2@sdsol.com",
    "firstName" => "Abrar",
    "lastName" => "Khan"
];
// Encode payload
$jsonPayload = json_encode($payload);
$encodedPayload = base64_encode($jsonPayload);
// Generate HMAC
$hmac = base64_encode(hash_hmac('sha256', $encodedPayload, $sharedSecret, true));

GET Request Example

 // Sample GET param
$param = "manojit9@gmail.com";
// Encode
$jsonParam = json_encode($param);
$encodedParam = base64_encode($jsonParam);
// Generate HMAC
$hmac = base64_encode(hash_hmac('sha256', $encodedParam, $sharedSecret, true));

Required Headers to Authenticate API Calls

When making API requests, you must include the following headers:

Authorization: Bearer <JWT_access_token>
X-AnnexCloud-Site: <site_id>
Content-Type: application/json

• Authorization: Contains the JWT token prefixed with "Bearer".
• X-AnnexCloud-Site: Your assigned site_id.
• Content-Type: Must be application/json for POST/PATCH requests.

NOTE: These headers are mandatory for every authenticated call to Annex Cloud public APIs.