Convert API supports two methods of API key authentication:

1. Request Signing (HMAC)

When using request signing, Convert API uses the Hash-based message authorization code (HMAC). Instead of having passwords that need to be sent over, we actually use Signing Method for API request validation. When you send HTTP requests to Convert, you sign the requests so that Convert can identify who sent them. So every request should contain Signature, calculated with the help of a Secret Key, Request URL, Request payload, Request Expiration time.

Three headers have to be sent with each request in order for the request to be authenticated correctly by Convert API:

• Convert-Application-ID: This is the ID you get from your account corresponding to the application created inside Convert App.
• Expires: This is a UNIX timestamp after which the request signing expires. The closer in future the timestamp is, the sooner the request signature would be invalidated and the more secure would be
• Authorization: The value of this one is as follows: Convert-HMAC-SHA256 Signature=[generated_hash]; The [generated_hash] is a request signature calculated applying sha256 hashing algorithm on ApplicationID, ExpiresTimestamp, RequestURL, RequestBody.

What could go wrong with request signing authorization? APP ID and APP Secret are right, but it is still UNAUTHORIZED!

• Check your system time - the time of the system where signature is generated
• Check the request duration between client and API and provide larger expiration time if it takes longer so that signature does not expire before reaching validation on Convert's servers
• Make sure that stringified payload and Sign String are correct and do not contain additional spaces. For Javascript just use JSON.stringify(request) for request payload. For php use additional flags for json_encode: json_encode($request, JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE)).
• Make sure you are using HMAC SHA256 to calculate the signature and provide this method (Convert-HMAC-SHA256) in the Authorization header value
• Make sure that nothing changes the payload after signature generation but before sending it

Example of the request signing signature generation in Javascript:

var SignString  = ApplicationID + "\n" + ExpiresTimestamp + "\n"  + RequestURL + "\n" + RequestBody;
var hash = CryptoJS.HmacSHA256(SignString, ApplicationSecretKey);
var hashInHex = CryptoJS.enc.Hex.stringify(hash);
var Authorization = "Convert-HMAC-SHA256 Signature=" + hashInHex;

For the above example, the Authorization header would be "Authorization: Convert-HMAC-SHA256 Signature=${Authorization}"

2. Secret Key

A simpler authentication method using a shared secret key. This method requires only a single header:

• Authorization: Include the key ID and key secret as a Bearer token in the format: Bearer KEY_ID:KEY_SECRET

The secret key method is easier to implement while still providing strong security. However, request signing provides additional security through request expiration and payload validation.

In order to use the Convert app, user has two options to authenticate requests:

• Provide authorization token with each request works best for backend systems
• Authenticate once using username/password/IDP provider and than send session token together with each request These endpoints will handle second case.

IMPORTANT: currently this is available only for Convert.com's own clients, all other third party clients need to authenticate using API KEY Authentication

Each response returned by API endpoints can have fields that are not returned by default, for improved performance, in many use cases where those fields would not be needed.

Important: Object returned as a response of a created/update operation would include also the optional fields of that object.

Those requests which can return optional fields specify the list of possible values for those fields names in an include parameter, described either as part of the URL, either as part of the request body.

Format

The include parameter must be an array when present. In URL parameters, use the following format:

include[]=field1&include[]=field2

Valid Examples

• Including stats and variations in an experience response:

  include[]=stats&include[]=variations
  

• Including rules and stats in an audience response:

  include[]=rules&include[]=stats.experiences_usage
  

Error Cases

• Invalid format (string instead of array):

  include=stats  # ❌ Wrong
  include[]=stats  # ✅ Correct
  

  Response:

  {
    "code": 422,
    "message": [
        "The 'include' parameter must be a array."
    ],
    "parameters": [
        "include"
    ]
  }
  

Fields mentioned in the include parameter can belong to Expandable Fields in which case that respective field would be expanded by default. Example: include[]=variations.changes for a getExperience operation, variations.changes is an expandable field of that response, which would then be expanded by default.

Each response returned by API endpoints can have fields that reference other objects, which are not returned in full by default. For example, the getExperience operation returns and Experience object which contains a project field. By default, this is a string and represents the ID of the referenced project object.

In some use cases, more data related to the respective object might be needed. The Convert API offers the ability to expand certain fields into a more detailed object identified by the ID that would be sent by default.

The expanded object is the same object that the get[Object] operation would return, not having though any of the Optional fields

Format

The expand parameter must be an array when present. In URL parameters, use the following format:

expand[]=field1&expand[]=field2

Valid Examples

• Expanding project and audiences in an experience response:

  expand[]=project&expand[]=audiences
  

• Expanding goals and variations in an experience response:

  expand[]=goals&expand[]=variations
  

Error Cases

• Invalid format (string instead of array):

  expand=project  # ❌ Wrong
  expand[]=project  # ✅ Correct
  

  Response:

  {
    "code": 422,
    "message": [
        "The 'expand' parameter must be a array."
    ],
    "parameters": [
        "expand"
    ]
  }
  

Authenticated user related endpoints