REST API v2¶

How to obtain an application access_token?¶

Curl example:

# Basic Authentication to get a valid Client OAuth Token
curl -X POST -u "$APPLICATION_ID:$APPLICATION_SECRET" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Accept: application/json" \
  -d "grant_type=client_credentials&scope=client&client_id=$CLIENT_ID" \
  "$BASE_URL/api/v2/client/tokens"

# => returns JSON object containing the access_token
{
  "access_token":"eyJhbGciOiJSUzI1NiIsInR5cCI....",
  "token_type":"bearer",
  "expires_in":3600
}

The access_token returned is valid until its expiration date, so you should check the validity of your token before making any call to our API. If the token is expired, you should just request a new OAuth application access token by calling the previous endpoint again.

Errors during access_token creation¶

If an error occurs during the generation of the access_token, you receive a JSON response with the following keys:

• error: machine-parseable error code refining the HTTP status code

• error_description: human readable description of the error

Wrong application_id or application_secret:

HTTP/1.1 401 Unauthorized

{
  "error": "invalid_client",
  "error_description": "Client authentication failed."
}

Wrong client_id:

HTTP/1.1 400 Bad Request

{
  "error": "invalid_request",
  "error_description": "The request is invalid"
}

Wrong scope:

HTTP/1.1 400 Bad Request

{
  "error": "invalid_scope",
  "error_description": "The requested scope is invalid."
}

Wrong grant_type (should be client_credentials):

HTTP/1.1 400 Bad Request

{
  "error": "invalid_grant",
  "error_description": "The provided authorization grant is invalid."
}

Access Token usage¶

The OAuth access_token token must then be provided in each API call in the Authorization HTTP header.

curl -X GET \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-type: application/json" \
  -H "Accept: application/json" \
  "$BASE_URL/api/v2/client/RESOURCES"

HTTP Status codes¶

Our API attempts to return appropriate HTTP status codes for every request:

• HTTP 200: the request is a success

• HTTP 201: the resource has been created

• HTTP 400 Bad Request: The request was invalid or cannot be otherwise served. Please review the error message in the body of the response for more details

• HTTP 401 Unauthorized: Authentication credentials were missing or incorrect

• HTTP 403 Forbidden: The request is understood, but it has been refused or access is not allowed

• HTTP 404 Not Found: The URI requested is invalid or the resource requested does not exist

• HTTP 422 Unprocessable Entity: When updating or creating resources, sending invalid fields results in a 422 Unprocessable Entity response with a JSON body containing error details on each field.

Error messages¶

When the API returns error messages, it does so in JSON format, with the following keys:

• code: machine-parseable error code refining the HTTP status code

• message: human readable description of the error

• errors: (optional) In case of input field validation errors (HTTP 422 Unprocessable Entity), the errors attribute contains the list of validation field errors. Each validation field error object has the following attributes:

  • field: key of the field in the input json payload

  • code: machine-parseable error code of the error

  • message: human readable description of the error.

HTTP 401 Unauthorized Example:

{
  "code": "invalid_token",
  "message": "The authentication token is expired",
}

HTTP 422 Unprocessable Entity Example:

{
  "code": "validation_error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "title",
      "code": "too_long",
      "message": "Title is too long"
    }
  ]
}

HTTP 422 Unprocessable Entity Example Nested example:

{
  "code": "validation_error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "category.title",
      "code": "too_long",
      "message": "Title is too long"
    }
  ]
}

HTTP 422 Unprocessable Entity Nested list example:

{
  "code": "validation_error",
  "message": "Validation failed",
  "errors": [
    {
      "field": "category.0.title",
      "code": "too_long",
      "message": "Title is too long"
    },
    {
      "field": "category.1.title",
      "code": "too_long",
      "message": "Title is too long"
    }
  ]
}

Error codes¶

The following list describes the main error codes. It is not an exhaustive list.

• invalid_request: The request is missing a required parameter, includes an unsupported parameter or parameter value, repeats the same parameter, uses more than one method for including an access token, or is otherwise malformed. The server responds with the HTTP 400 Bad Request status code.

• invalid_token: The access token provided is expired, revoked, malformed, or invalid for other reasons. The server respond with the HTTP 401 Unauthorized status code.

• invalid_credentials: The credentials are missing or invalid. The server respond with the HTTP 401 Unauthorized status code.

• insufficient_scope: The request requires higher privileges than provided by the access token. The server responds with the HTTP 403 Forbidden status code.

• invalid_client_id: Client not valid or not found. The server respond with the HTTP 400 Bad Request status code

• validation_error: The input payload contains validation errors. The server respond with the HTTP 422 Unprocessable Entity status code