API Authentication
Using the API requires an authentication. Depending on the use case of the API there are two different ways how to authenticate.
Whenever you are a retailer and just want to provide product feed updates via an API this approach is sufficient. Request the API key for your publisher at your Pentaleap contact.
A sample request looks like the following:
Whenever you are maintaining multiple publishers under your organization you need to request separate API keys for each publisher.
The following v2 API endpoints can be authorized using an API key:
Whenever you are a partner and want to e.g. manage campaigns via an API, you need to request an access token from Auth0, specifically a JSON Web Token (JWT). Consider using one of the client libraries provided by Auth0 which fits your use case and technical implementation.
There are a couple of prerequisites needed in order to do an OAuth2 based authorization flow:
- Request a client id as well as user credentials (the same ones which will be used to login into the Pentaleap platform) at your Pentaleap contact.
- Ask Pentaleap to register your callback URI API endpoint.
The mentioned prerequisites are required for each environment, typically sandbox and production.
The following steps describe the authorization code flow. For a more elaborate documentation please refer to the Auth0 documentation.
The first step requires calling the following URL, and then logging into the Pentaleap platform using your user credentials:
- scope refers the scopes for which the authorization should be requested. The sample above contains all scopes required for version 2 of the API (read:publishers, write:publishers, read:advertisers, write:advertisers, read:campaigns, write:campaigns, read:ad_groups, write:ad_groups, read:sites read:ad_units, read:publisher_reports) as well as the offline_access scope for retrieving refresh tokens.
- The scopes read:campaign_products, write:campaign_products, and read:ad_grids are deprecated for now and are only required for version 1 of the API.
- state is a recommanded query parameter to be added to this initial request which Auth0 includes whenever it redirects to your callback URI. It helps prevent CSRF attacks (see Auth0 documentation).
When all goes well Auth0 redirects then uses the following URL:<callback-uri>?state=<some-state>&code=<code-generated-by-auth0>
Use the code in the query string in order to request a new token:
The response contains an access token and its validity (expires_in) in seconds as well as a refresh token.
Use the access token for requests to the Campaign and Reporting API. A sample request looks like the following:
As long as the access token is not expired, the token can be reused for an arbitrary amount of requests. In order to issue a new access token, use the request token in the following way:
The response contains a new access token as well as a new refresh token. Each refresh token value must be used only once. Consequently, this new refresh token must be used for the next token request with grant_type=refresh_token. Whenever a refresh token is used twice, any refresh token is invalidated immediately and the whole OAuth2 authorization flow has to be performed again (see Auth0 documentation for more details). In any case, the authorization flow has to be redone after 180 days.