All Versions

Version 1
Version 2


Page tree

Supplier API v2

Skip to end of metadata
Go to start of metadata

Table of Contents

Overview

HTTP Basic Authentication

Most endpoints provided by this API require authentication using HTTP Basic Authentication. This authentication method is a well established and widely implemented form of web authentication. Many programming languages and frameworks provide built-in facilities to handle this automatically. Following is a simple example of how HTTP Basic Authentication can be manually implemented. 

Using HTTP Basic Authentication, your username and password are used to create an authorization token. The authorization token is constructed as follows using the example credentials below:

username: criticalmix
password: topsecret

  1. The username and password are combined with a single colon (:) 
    criticalmix:topsecret
  2. The resulting string is encoded using Base64.
    Y3JpdGljYWxtaXg6dG9wc2VjcmV0


This is your authorization token.

Providing Your Credentials

Critical Mix will provide you with a username and password as a part of the on-boarding process for the use of this API.

Your username will be the same for our production and sandbox environments, but passwords will be different!

Use the Authorization header to provide your authorization token for any endpoint which requires authentication. The Authorization header requires two values separated by a space. 

The first value is the type of authentication being used. In this case, the type should be Basic.
The second value is your authorization token.

Given the authorization token Y3JpdGljYWxtaXg6dG9wc2VjcmV0 from the above example, the Authorization header would look like this:

Authorization: Basic Y3JpdGljYWxtaXg6dG9wc2VjcmV0

Related Errors

Requests which require authentication, as specified in the Endpoints documentation, will evaluate the Authorization header and validate your credentials. Requests that do not require authentication will ignore the Authorization header.

Authentication errors may not be generated by endpoints which do not require authentication, even if invalid credentials are provided!


HTTP StatusError CodeDescription
401: Unauthorizedauthorization-requiredThe Authorization header is missing from the request for an endpoint which requires authentication.
basic-authorization-requiredThe authentication type is not specified in the Authorization header is not Basic.
invalid-authorizationThe authorization token provided in the Authorization header cannot be successfully decoded.
403: Forbiddeninvalid-credentialsAn invalid username or password was used to create the authorization token.

Example: Proper Use of the Authorization Header

The following example illustrates the correct use of the Authorization header in a request for a members resource, which requires authentication.

GET /api/v2/members/M0001
Accept: application/json
Accept-Version: 1.0
Authorization: Basic Y3JpdGljYWxtaXg6dG9wc2VjcmV0

HTTP/1.1 200
Content-Type: application/json; charset=utf-8
Content-Version: 1.0
{
  "memberId": "M0001", 
  "language": "EN", 
  "email": "m0001@example.com",
  "firstName": "John",
  "lastName": "Snow",
  "birthDate": "1984/01/20",
  "address": { 
    "country": "US",
    "streetAddress": null,
    "postalcode": "10101"
  } 
}

Example: Missing Authorization Header

This example shows a request to the members resource which requires authentication. But, the Authorization header is missing from the request.

An appropriate error response is returned.

GET /api/v2/members/M0001
Accept: application/json
Accept-Version: 1.0

HTTP/1.1 401
Content-Type: application/json; charset=utf-8
{
  "errorCode": "authorization-required",
  "errorMessage": "Authorization is Required",
  "errors": []
}

Example: Incorrect Authentication Type

In this example, the request to  members requires authentication. But, the authentication type is specified as OAuth instead of Basic.

An appropriate error response is returned.

GET /api/v2/members/M0001
Accept: application/json
Accept-Version: 1.0
Authorization: OAuth YmFkOmNyZWRlbnRpYWxz

HTTP/1.1 401
Content-Type: application/json; charset=utf-8
{
  "errorCode": "basic-authorization-required",
  "errorMessage": "Authorization must be HTTP Basic Authorization",
  "errors": []
}

Example: Invalid Credentials Used

This example shows a request to the members resource which requires authentication. But, invalid credentials were used to create the authorization token.

An appropriate error response is returned.

GET /api/v2/members/M0001
Accept: application/json
Accept-Version: 1.0
Authorization: Basic YmFkOmNyZWRlbnRpYWxz

HTTP/1.1 403
Content-Type: application/json; charset=utf-8
{
  "errorCode": "invalid-credentials",
  "errorMessage": "Invalid Authentication Credentials",
  "errors": []
}

 

  • No labels
Write a comment…