All Versions

Version 1
Version 2


Page tree

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Added content and reformatted the page

Table of Contents

Table of Contents
maxLevel4
excludeTable 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. Below, we provide a simple example of how HTTP Basic Authentication can be manually implemented. Many programming languages and frameworks provide built-in facilities to handle this automatically. 

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.

Info

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

Using  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 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

your authorization token.

HTTP Header: Authorization

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.

Info

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.

Info

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.

Example
UI Tabs


UI Tab
titleJSON


No Format
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
{
  
... }

Authorization 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.

Info

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

401: Unauthorized

The API will return an HTTP Status of 401: Unauthorized if any of the following conditions are true.

  1. The Authorization header is missing from the request for an endpoint which requires authentication
    For this case, an error response will also be included with "errorCode": "authorization-required"
  2. The authentication type is not specified as Basic
    For this case, an error response will also be included with "errorCode": "basic-authorization-required"
  3. The authorization token cannot be successfully decoded
    For this case, an error response will also be included with "errorCode": "invalid-authorization"
Example
"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.

UI Tabs


UI Tab
titleJSON


No Format
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.

UI Tabs


UI Tab
titleJSON


No Format
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 
is Required" }

403: Forbidden

An HTTP status of 403: Forbidden is returned if an invalid username or password is
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 will also be included with "errorCode": "invalid-credentials"

Example

is returned.

UI Tabs


UI Tab
titleJSON


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

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




 

Excerpt
hiddentrue

Describes the authentication process for requests made to this API