Partner API
API Reference

OAuth 2.0 Authentication

📘

OAuth 2.0 is only available on the /ads endpoint

When integrating order reporting via API, you will need to integrate the /orders endpoint with Basic authentication and your secret API key.

Client ID and Client Secret

The client_id and the client_secret will be provided by your Technical Account Manager. The Client Secret is private and should not be shared.

Requesting Access Tokens

To obtain an Access Token, you must send a request containing the client_id and client_secret. To do that, the Retailer must make a POST request to the CitrusAd Authorization Server endpoint:

https://$BASE_URL/v1/oauth2/token

📘

/oauth2/token only provides the relevant token. You will use these tokens to interact with the various integration endpoints.

Your request will require a Basic Authorization sent via the Authorization request header containing the Retailer’s client_id and client_secret base64 encoded:

Authorization: "Basic" + base64encode(client_id + ":" + client_secret)

You will need to add the following parameter using the application/x-www-form-urlencoded format in the HTTP request body:

grant_type=client_credentials

The request will look like the following:

POST https://$BASE_URL/v1/oauth2/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic <base64 encoded id+key>
grant_type=client_credentials

Receiving your Access Token

The response will contain the following information

  • access_token: The access token to be used when calling the CitrusAd APIs
  • expires_in: The amount, in seconds, until the access token expires
  • token_type: The type of the token returned. It will be always Bearer in this case

A sample response is below

{
  "access_token": "xxxxx.yyyyy.zzzzz",
  "expires_in": 3600,
  "token_type": "Bearer"
}

Using the Token

Making calls against the CitrusAd API endpoints can be done by simply adding the Access Token generate to the Authorization header on the request
Authorization: “Bearer “ <access_token>

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Bearer <access_token>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
         ["category:Cupboard/Snacks"]
    ],
    "options": {
                             "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 3
}

Request Errors

Invalid Client

If the client_id or client_secret sent in the request is incorrect, then you will receive a response like this:

{
  "error": "invalid_client"
}

Make sure you are using the correct credentials. Double-check your client_id and client_secret and make sure you're using the Basic Authorization correctly when calling the /token endpoint.
##Invalid Request
An invalid request error will be returned from the Authorization Server if the request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.

{
  "error": "invalid_request"
}

Ensure to:

  • Only include grant_type=client_credentials to the request body
  • Set the correct Content-Type to the request header