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 APIsexpires_in
: The amount, in seconds, until the access token expirestoken_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