How to generate the Authorization header

How to generate the Authorization header

Info
This guide provides a detailed explanation of how to generate an Authorization header for an API request using cryptographic operations. The process involves creating a JSON request body, hashing an API key with SHA-256, and then using that hash to compute an HMAC-SHA256 signature of the body. The resulting signature (as a hexadecimal string) becomes the value of the Authorization header.

Prerequisites

  • API Key and Vendor Details: You'll need a secret VENDOR_API_KEY (a string) and VENDOR_NUMBER (a string identifying your account)

  • Cryptographic Libraries: Most programming languages have built-in or standard libraries for SHA-256 hashing and HMAC:

    • JavaScript/Node.js: crypto module.

    • Python: hashlib and hmac modules.

    • Java: java.security and javax.crypto.

    • Other languages (e.g., C#, Go, Ruby) have equivalents—adapt as needed.

  • JSON Handling: Ensure your environment can serialize objects to JSON strings without extra whitespace.

  • Best Practices:

    • Store the API key securely.

    • Never commit secrets to version control.

    • Use UTF-8 encoding for all string operations.

Step 1: Construct the Request Body

  • Create a JSON object with the structure required by the endpoint.

  • Serialize the object to a JSON string. Ensure consistent formatting (e.g., no unnecessary spaces or sorting changes) to avoid signature mismatches.

Step 2: Compute the SHA-256 Hash of the API Key

  • Take the raw API key string.

  • Encode it as UTF-8 bytes.

  • Apply SHA-256 hashing to produce a 32-byte (256-bit) digest. This digest acts as a derived secret key for the HMAC, enhancing security.

Step 3: Compute the HMAC-SHA256 Signature

  • Use the SHA-256 digest from Step 2 as the secret key.

  • Use the JSON string from Step 1 as the message.

  • Compute the HMAC-SHA256, which produces another 32-byte digest.

  • Convert this digest to a lowercase hexadecimal string (64 characters).

Step 4: Set the Authorization Header

  • Use the hexadecimal string as the value for the Authorization header in your HTTP request (e.g., Authorization: <hex_string>).

  • Send the request with the exact JSON body used for signing. Any mismatch will invalidate the signature.

Code Examples


  1. const crypto = require('crypto');

    function generateAuthorization(vendorApiKey, vendorNumber, referenceId) {
      const bodyObj = {
        vendorNumber: vendorNumber,
        referenceID: referenceId,
        includes: {
          names: true,
          latinNames: true,
          address: true,
          documentType: true,
          documentNumber: true,
          documentIssuerName: true,
          documentValidDate: true,
          documentIssueDate: true,
          documentCountry: true,
          identificationNumber: true,
          gender: true,
          nationality: true,
          documentPicture: true,
          documentSignature: true,
          picFront: true,
          picBack: true,
          dateOfBirth: true,
          placeOfBirth: true
        }
      };

      const body = JSON.stringify(bodyObj);

      // SHA-256 hash of API key
      const apiKeyHash = crypto.createHash('sha256').update(vendorApiKey).digest();

      // HMAC-SHA256 of body
      const hmac = crypto.createHmac('sha256', apiKeyHash).update(body).digest('hex');

      return hmac;
    }

    // Example usage
    const authHeader = generateAuthorization('XXX', 'XXX', 'XXX');
    console.log('Authorization:', authHeader);

    // In a real app, add to headers: headers: { Authorization: authHeader }




    • Related Articles

    • How to Generate Your Public and Private Keys

      This guide explains how to generate an RSA 2048-bit key pair in PKCS#8 format, and prepare them for use in API requests. RSA is an asymmetric encryption algorithm where the public key is used for encryption, and the private key for decryption. This ...

    • Implement Document Signing via Evrotrust Application

      This guide provides a step-by-step process for integrating the Evrotrust API to enable document signing via the Evrotrust mobile app. The flow involves checking user status, sending documents for signing, handling callbacks, checking status ...

    • Receive a Callback From Evrotrust

      This guide explains how to set up and handle callbacks from Evrotrust. Callbacks are asynchronous notifications sent by Evrotrust to your server when certain events occur (e.g., a document is signed, expires, or is rejected). These notifications ...

    • User Guide - Evrotrust Support Portal - Zoho Desk

      Тable of Contents Summary & Overview Purpose of This Guide How to Use the Evrotrust Support Portal 1. Registration, Login & Forgotten Password 1.1 First-Time Access 1.2 How to Log In 1.3 How to Reset a Password 2. Navigating the Portal 2.1 Home ...

    • Document Decryption Guide

      This guide provides a step-by-step explanation of the decryption process for the encrypted file in the result of document/download. The scheme combines RSA (asymmetric encryption) to encrypt a symmetric key and AES (symmetric encryption) in CBC mode ...