This document explains the use of Basic Authentication for securing API requests. Integrators must implement Basic Authentication in their integration layer using a combination of a username and a password, encoded into a single string.

Overview

In our API, Basic Authentication is used to ensure that requests are made by authorized integrators on behalf of providers. The credentials used are:

  • Username: provider_id

  • Password: access_key

These credentials are specific to each provider and must be used in every request your integration layer makes to the API.

Header Format

The credentials must be sent in the Authorization header of the HTTP request. The format of the header is as follows:

Authorization: Basic <encoded_credentials>

<encoded_credentials>: This is a Base64 encoded string combining the provider_id and access_key, separated by a colon (:).

Example

Assuming:

  • provider_id: 12345

  • access_key: abcde12345

The credentials would be combined as follows:

12345:abcde12345

These combined credentials are then encoded using Base64. Below is how the encoding process works.

Calculation

  1. Combine the credentials:

    Combine the provider_id and access_key with a colon:

    12345:abcde12345

  2. Encode with Base64:

    Encode the combined string using Base64. You can use various tools or libraries (e.g., Python, JavaScript, or an online encoder) to encode the string. The encoded result will look something like:

    MTIzNDU6YWJjZGUxMjM0NQ==

  3. Send in the request header:

    Add the encoded string to the Authorization header:

    Authorization: Basic MTIzNDU6YWJjZGUxMjM0NQ==

Why Use Basic Authentication?

Basic Authentication provides a straightforward way to secure API requests, ensuring that only authorized integrators can access the system. Here are the key reasons why Basic Authentication is used:

  • Simple and Effective: It is easy to implement and provides a quick way to secure APIs without the need for complex token management systems.

  • Provider Specific: Each provider has unique credentials (provider_id and access_key), allowing for secure, provider-specific access from your integration layer.

  • Encryption Ready: When used over HTTPS, the credentials are transmitted securely, protecting them from being exposed during transmission.

Important

Always ensure that Basic Authentication is used over HTTPS to prevent credentials from being exposed to unauthorized parties.

Summary

Basic Authentication serves as a fundamental security measure, ensuring that each API request is authenticated with specific provider credentials. By correctly setting up the Authorization header with encoded credentials, your integration layer can securely access the system’s resources.

Note

The access key should never be shared or exposed in client-side code or public repositories. Always handle private keys securely.