{"templateId":"openapi_docs","sharedDataIds":{"openAPIDocsStore":"oas-loyalty/loyalty.yaml","sidebar":"sidebar-sidebars.yaml"},"props":{"definitionId":"loyalty/loyalty.yaml","dynamicMarkdocComponents":[],"baseSlug":"/loyalty/loyalty","seo":{"title":"JWT Authentication","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]},"description":"Annex Cloud Loyalty API Authentication Guide\n\nOverview\n\nAccess 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:\n\nAuthorization: Bearer <token> header in the HTTP request.\n\nFailure 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:\n\nThe 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.\n\nStep-by-Step Authentication Flow\n\n1. Request Payload Handling\n\n\n   POST Requests\n\n\n- The raw JSON request body must be used exactly as sent (including character encoding).\n\n- No JSON normalization or reordering should be performed.\n\n- The body must be UTF-8 encoded and then Base64-encoded.\n\n\n   GET Requests\n\n\n- The request identifier (e.g., user_id) must be treated as a JSON string literal.\n\n- The value must be wrapped in double quotes (\"value\").\n\n- The quoted string must be UTF-8 encoded and then Base64-encoded.\n\n\n2. HMAC Generation\n\n- The Base64-encoded payload is hashed using HMAC-SHA256.\n\n- The raw secret key must be used (do not Base64-encode the key).\n\n- The resulting HMAC must be Base64-encoded.\n\n\n   Formula: HMAC = Base64( HMAC-SHA256( Base64(payload), secret_key ) )\n\n\n   This HMAC uniquely binds the JWT to the specific request content.\n\n\n\n3. JWT Payload Structure\n\n\n    The JWT payload contains standard claims along with the computed HMAC:\n\n\n    Field\tDescription\n\n\n- sub\tAssigned site name\n\n- exp\tExpiration timestamp (Unix time in seconds)\n\n- site_id\tAssigned site identifier\n\n- hmac\tBase64-encoded HMAC of the request payload\n\n\n       Example:\n\n\n              {\n\n\n                \"sub\": \"SITE_NAME\",\n\n\n                \"exp\": 1700000000,\n\n\n                \"site_id\": 12345678,\n\n\n                \"hmac\": \"q8P1ZtRk8fPZ5ZyM...\"\n\n\n              }\n\n\n\n4. JWT Construction and Signing\n\n\n          JWT Header:\n\n          \n          {\n\n\n            \"alg\": \"HS256\",\n\n\n            \"typ\": \"JWT\"\n\n\n          }\n\n\n- The header and payload must be Base64URL-encoded.\n\n- The token must be signed using HMAC-SHA256 with the same secret key.\n\n- Final token format: Base64Url(header).Base64Url(payload).Base64Url(signature)\n\n\n5. Sending the Token\n\n\n    The JWT must be included in the HTTP header:\n\n\n- Authorization: Bearer <JWT_TOKEN>\n\n\n\n    Each request requires a newly generated token, as the HMAC is tied to the specific request payload.\n\n    \n    Important Notes\n\n\n- UTF-8 encoding must be preserved, especially for non-ASCII characters (e.g., accented characters).\n\n- POST payloads must not be reformatted or re-serialized after signing.\n\n- GET request parameters must be wrapped in double quotes before hashing.\n\n- Tokens expire and must be regenerated for each request.\n\n\n\n    For further assistance, please contact your Annex Cloud Customer Enablement Manager or Customer Success Manager."},"itemId":"jwt-authentication","disableAutoScroll":true,"metadata":{"subType":"openapi-operation"},"compilationErrors":[],"markdown":{"partials":{},"variables":{"rbac":{"teams":["anonymous"]},"user":{},"remoteAddr":{"hostname":"annexcloud.redocly.app","port":4000,"ipAddress":"216.73.216.182"},"lang":"default_locale","env":{"PUBLIC_REDOCLY_BRANCH_NAME":"master"}}},"pagePropGetterError":{"message":"","name":""}},"slug":"/loyalty/loyalty/jwt-authentication","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}