RTB API

Using merchenta.io for real-time bidding

Authentication 

Before you can create campaigns or do reporting calls, your application needs to be authenticated. Authentication is performed using a standard OAuth 2.0 mechanism where an access token is generated and used in subsequent RTB API operations. Each access token is a secure, opaque string that identifies a user and can be used by the application to make API calls. The token includes information about when the token will expire and which user and advertiser code it was generated for. The majority of API calls on RTB API need to include an access token passed on the HTTP header.

Access tokens are obtained via an authentication endpoint described in detail below.

Generate authentication token 

/v3/oauth/accessToken?username={username}&password={password}&advertiser={advertiser}

Generates authentication token valid for given advertiser code.

  • Parameters
  • username
    string (required) Example: username

    username

    password
    string (required) Example: password

    password

    advertiser
    string (required) Example: MERCHENTA

    advertiser code

  • Curl
  • Copy
    curl -i \ -X GET \ https://sandbox.rtbapi.io/v3/oauth/accessToken?username=username&password=password&advertiser=MERCHENTA
  • Response  200
  • Headers
    Content-Type: application/json
    Example body
    {
            "status": "success",
            "data": {
                "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZHYiOiJNRVJDSEVOVEEiLCJleHAiOiIyMDE0LTEwLTA3VDEwOjIwOjEyLjQ4OSIsInJsbSI6IkFETUlOIiwidXNyIjoidGVzdEBtZXJjaGVudGEuY29tIiwiaWF0IjoiMjAxNC0xMC0wN1QwOToyMDoxMi40NTAifQ.7fb8007c49abb7e083f4aca024512ef3c9d32ea1ab0502d2603f4c2c92545b80"
            }
        }

Access tokens 

API access tokens are short-lived and have a lifetime of about an hour. You should not depend on token lifetimes remaining the same - the lifetime may change without warning or expire early. See more under handling authentication errors. The best way to handle expired tokens is to capture the error messages thrown by the API. By checking for the HTTP error status code 401 and the error code AUTH001 in the JSON body, you can determine that you are no longer considered to be authenticated and you should obtain a new access token and then retry. If you fail for a 2nd time, another reason exists for your failed access.

Token based authentication 

Now as you have a valid access token you can access the RTB API resources. For this to work properly you need to pass the access token using the Authorization HTTP header in the form:

Authorization: Bearer {YOUR_TOKEN_HERE}

for example

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJhZHYiOiJNRVJDSEVOVEEiLCJleHAiOiIyMDE0LTEwLTA3VDEwOjIwOjEyLjQ4OSIsInJsbSI6IkFETUlOIiwidXNyIjoidGVzdEBtZXJjaGVudGEuY29tIiwiaWF0IjoiMjAxNC0xMC0wN1QwOToyMDoxMi40NTAifQ.7fb8007c49abb7e083f4aca024512ef3c9d32ea1ab0502d2603f4c2c92545b80

Handling authentication errors 

Expired, invalid or missing access tokens

As access tokens have finite lifetime it is possible to attempt API access with an expired token. In such a case you will receive a response with 401 HTTP status (Unauthorized) as shown below:

{
    "status": "error",
    "message": "Authentication required - pass access token using 'Authorization' header",
    "code": "AUTH001"
}

The best way to handle token expiration is to automatically re-generate the token and retry the request which failed with the 401 HTTP status code.

Authorization failed

In the RTB API we provide different levels of access to the platform. In the case where you are authenticated, but not authorized to access a given resource, you will receive a response with 403 HTTP status (Forbidden) as shown below:

{
    "status": "error",
    "message": "Authorization failed",
    "code": "AUTH003"
}

Token size 

You should allow for changes in the size of the access tokens as we make changes to what is stored in them and how they are encoded. They may grow or shrink. Therefore please use a variable length data type without a specific maximum size when you store your access tokens.

Next page  Previous page