API Authentication

using the api requires an authentication depending on the use case of the api there are two different ways how to authenticate api key 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 curl request get \\ \ url 'https //\<pcm domain>/external/v2/publishers/\<publisher id>/markets/\<market id>/products/search?limit=100' \\ \ header 'authorization apikey \<api key>' 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 get https //\<pcm domain>/external/v2/publishers/\<publisher id>/markets/\<market id>/products/search get https //\<pcm domain>/external/v2/markets access token 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 the following at your pentaleap contact client id auth0 domain auth0 audience identifier user credentials (the same ones which will be used to login into the pentaleap platform ) 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 1\ the first step requires calling the following url, and then logging into the pentaleap platform using your user credentials https //\<auth0 domain>/authorize ?audience=\<audience identifier> \&response type=code \&client id=\<client id> \&redirect uri=\<callback uri> \&scope=offline access%20read%3apublishers%20write%3apublishers%20read%3aadvertisers%20write%3aadvertisers%20read%3acampaigns%20write%3acampaigns%09read%3aad groups%20write%3aad groups%20read%3asites%09read%3aad units%20read%3apublisher reports \&state=\<some state> 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> 2\ use the code in the query string in order to request a new token curl request post \\ \ url 'https //\<auth0 domain>/oauth/token' \\ \ header 'content type application/x www form urlencoded' \\ \ data grant type=authorization code \\ \ data 'client id=\<client id>' \\ \ data 'code=\<code generated by auth0>' \\ \ data 'redirect uri=\<callback uri>' the response contains an access token and its validity ( expires in ) in seconds as well as a refresh token 3\ use the access token for requests to the campaign and reporting api a sample request looks like the following curl request get \\ \ url 'https //\<pcm domain>/external/v2/publishers' \\ \ header 'authorization bearer \<access token>' 4\ 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 curl request post \\ \ url 'https //\<auth0 domain>/oauth/token' \\ \ header 'content type application/x www form urlencoded' \\ \ data grant type=refresh token \\ \ data 'client id=\<client id>' \\ \ data 'refresh token=\<refresh token>' 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