Customer SupportGet Expert Help
Skip to main content

sha256_a Token Algorithm

Overview​

The "sha256_a" token Algorithm is a mechanism for authenticating URL requests based on tokens included in the query parameters. It verifies that a request is authorized by:

  • Checking time constraints defined by start and end times.
  • Optionally matching the client's IP address.
  • Validating a cryptographic hash (HMAC-SHA1) of the entire URL. The checker uses secret keys shared among client and server.

Multiple secrets can be configured simultaneously. Tokens will be checked against each configured secret and only one secret is required to match. This provides smooth key rotation without downtime.

Token Query Parameters​

It expects the following query parameters in the URL:

Required parameters​

ParameterTypeRequiredDescription
encodedStringMandatoryA cryptographic hash (token) of the entire URL (including path and query parameters), excluding the encoded parameter itself.
stimeStringMandatoryThe start time from which the token is valid in the format YYYYMMDDhhmmss.
etimeStringMandatoryThe end time until which the token remains valid in the format YYYYMMDDhhmmss.
ipStringOptionalSpecifies the IP address from which the request must originate.

Generation Algorithm​

Prepare the Base URL​

Start with the exact URL that the client will request, including the path and all existing query parameters, except for the encoded parameter. Ensure that the query parameters are in the exact order they will be sent, as the order affects the hash computation.

Add Time Parameters​

Start Time (stime): Add a query parameter specifying the start time from which the token is valid. End Time (etime): Add a query parameter specifying the end time until which the token remains valid. The time format for both parameters should be YYYYMMDDhhmmss, representing UTC time.

Example: 20231009120000 for October 9, 2023, at 12:00:00 UTC.

Optional IP Address Restriction​

If IP restriction is desired, add the ip query parameter with the client's IP address. The request will only be authenticated if it originates from this IP address.

Construct the String to Sign​

Create a string by concatenating the URL path and the query string, excluding the encoded parameter. Ensure that the path starts with a / and that the query parameters are properly URL-encoded. This string represents the exact request without the authentication token.

Compute the HMAC-SHA1 Hash​

Use the HMAC-SHA1 algorithm to compute a hash of the string constructed in the previous step. Use the shared secret key (known only to the server and the token generator) as the HMAC key. The hash output is a binary digest.

Process the Hash Output​

Convert the binary hash digest to a hexadecimal string. Keep only the first 20 hexadecimal digits of the hash. Prepend a "0" character to the truncated hash. This results in a 21-character hexadecimal string starting with "0".

Add the encoded Parameter​

Add the encoded query parameter to the URL. Set its value to the processed hash from the previous step. The encoded parameter is the authentication token that the server will validate.