Skip to main content

Authorization

The API uses Basic Authentication with a Base64 encoded string. There are two authentication modes: Client-Level and Product-Level. If the Authorization header is missing or incorrect, the endpoint will return a 401 Unauthorized error.

If the X-Product-Id header is present on the request, product-level authentication is used. Otherwise, client-level authentication is used. The two modes are mutually exclusive per request.

Client-Level Authentication​

Client-level authentication uses a Base64 encoded string in the format of ClientId:ApiKey.

Example of a Valid Client-Level Authorization Header​

For instance, if:

  • ClientId = LAGERMAN
  • APIKey = 87ba874b8a5049beadc9710984606715


The Basic Authentication text before encoding is:

LAGERMAN:87ba874b8a5049beadc9710984606715


After encoding in Base64, the text becomes:

TEFHRVJNQU46OTQzZjM2Mjk0N2EyNDA0NTgyYTI2ODkzN2QyM2JjMzM=


To use this in the Authorization header:

  • Header Name: Authorization
  • Header Value: Basic TEFHRVJNQU46ODdiYTg3NGI4YTUwNDliZWFkYzk3MTA5ODQ2MDY3MTU=

Product-Level Authentication​

Product-level authentication allows a product to act on behalf of a client. It requires three elements on the request:

  1. Authorization header: Basic base64(ProductId:ProductApiKey)
  2. X-Product-Id header: Must match the ProductId used in the Authorization header.
  3. X-Client-Id header: The ClientId on whose behalf the product is acting.

The ProductId and ProductApiKey are validated against the product API keys store. On success, both the ClientId (from X-Client-Id) and the ProductId (from X-Product-Id) are associated with the checkout session.

Example of a Valid Product-Level Authorization​

For instance, if:

  • ProductId = MYPRODUCT
  • ProductApiKey = abc123def456ghi789jkl012mno345pq
  • ClientId = LAGERMAN


The Basic Authentication text before encoding is:

MYPRODUCT:abc123def456ghi789jkl012mno345pq


After encoding in Base64, the text becomes:

TVlQUk9EVUNUOmFiYzEyM2RlZjQ1NmdoaTc4OWprbDAxMm1ubzM0NXBx


The required headers are:

  • Authorization: Basic TVlQUk9EVUNUOmFiYzEyM2RlZjQ1NmdoaTc4OWprbDAxMm1ubzM0NXBx
  • X-Product-Id: MYPRODUCT
  • X-Client-Id: LAGERMAN