Authentication Overview

Blameless provides oAuth flows to authorize access to the Blameless API. The client credential’s oAuth flow is used for machine to machine application and allows authentication of the application without involving an end user. Authentication tokens are passed using an auth header and are used when interacting with the API. All requests to the Web API require authentication.

Prerequisites

In order to obtain authentication tokens via API, please reach out to your Customer Success Manager (CSM) and they can provide you with your client ID and secret.

Fetching Auth/Refresh Tokens

Once you have the Client ID and Client secret, to fetch tokens you need to make a POST request to blamelesshq.auth0.com/oauth/token.

Sample Request

curl https://blamelesshq.auth0.com/oauth/token \
-X POST \
-H 'content-type: application/json' \
-d
'{
"client_id": <client id>,
"client_secret": <client secret>,
"audience": "<customer>.blameless.io",
"grant_type": "client_credentials"
}'

Sample Response

{
"access_token": "<ACCESS TOKEN>",
"token_type": "Bearer"
}

Authentication Errors

The Blameless Web API uses two different formats to describe an error:

  • Authentication Error Object
  • Regular Error Object
note

Regular Error Object is explained later in the reference materials.

Authentication Error Object

Whenever the application makes requests related to authentication or authorization to Web API, such as retrieving an access token or refreshing an access token, the error response follows the OAuth 2.0 Authorization Framework.

KeyValue TypeValue Description
errorstringA high level description of the error.
error_descriptionstringA more detailed description of the error.

Here is an example of a failing request to refresh an access token.

$ curl -H "Authorization: Basic YJYjc...K" -d grant_type=refresh_token -d refresh_token=AKOD...f0 "https://blamelesshq.auth0.com/oauth/token"
{
"error": "invalid_client",
"error_description": "Invalid client secret"
}

Refer to the Auth0 Documentation regarding error codes and descriptions.

Other Error Response Codes

Whenever the application makes requests related to authentication or authorization to Web API, such as retrieving an access token or refreshing an access token, the error response follows the OAuth 2.0 Authorization Framework.

Regular Error Object

Apart from the normal responses, unsuccessful responses return a JSON object containing the following information:

KeyValue TypeValue Description
statusintegerThe HTTP status code that is also returned in the response header. For further information, see Response Status Codes.
messagestringA short description of the cause of the error.

Here, is an example of the error that occurs when trying to fetch information for a non-existent or invalid ID:

\$ curl -i "https://https://\\\<customer\\\>.blameless.io/api/v1/\\\<ID\>\\"
HTTP/1.1 400 Bad Request
{
"error": {
"status": 400,
"message": "invalid id"
}
}