Get Authentication Credentials to Authorize With Adform APIs

OAuth authorization protocol uses these terms:

OAuth 2.0 in Adform provides several authorization methods that support different use cases and application types. In addition, Adform partially supports OpenID Connect (OIDC) protocol that adds to OAuth 2.0 and can be used for authentication and to obtain user's information. See OIDC protocol's discovery document for the list of supported authorization URIs, token, user information, and public-keys endpoints.

To simplify authorization with Adform APIs, you need to cache these authorization and token endpoints that are provided in the discovery document:

{
"authorization_endpoint": "https://id.adform.com/sts/connect/authorize",
"token_endpoint": "https://id.adform.com/sts/connect/token",
}

To get authentication credentials and authorize with Adform APIs, you need to register an OAuth client. To register an OAuth client, contact Adform Support (technical@adform.com) and provide:

Additionally, provide this information depending on the authorization method that you use:

After processing your request, Adform Support team will provide your API credentials via email. To check your credentials:

To register an OAuth client, you must provide the authorization method that you use. The choice of authorization method depends on what type of integration you have.

Client Credentials Authorization Method

We recommend to use this method for service-to-service integrations that don’t involve end user authentication. In this method, the user is integrated with a client (application).

The most common use cases for this method are:

• Automated reporting data retrieval

• Automated campaign data management

• Automated tracking URLs modifications

Client credentials method chart:

You can obtain the access token with an HTTP POST request:

POST https://id.adform.com/sts/connect/token HTTP/1.1
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&
client_id=<CLIENT_ID>&
client_secret=<CLIENT_SECRET>&
scope=<SCOPES>

Request body parameters:

Name	Description
grant_type	Must be client_credentials.
client_id	The username you receive with your OAuth client credentials. Must be included either in POST request body, or Base64 encoded in a basic authorization header.
client_secret	The password you receive with your OAuth client credentials. Must be included either in POST request body, or Base64 encoded in a basic authorization header.
scope	One or more space-separated scopes that you need access to.

The response is a JSON-encoded object:

{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": <EXPIRATION_TIME>,
  "token_type": "Bearer"
}

Response body parameters:

Name	Description
access_token	The requested access token. You can use it to access a secured resource, such as a web API.
expires_in	The token's duration in seconds. Once the token expires, you'll need to request it again.
token_type	The token's type. In this case, a Bearer token.

Authorization Code Method

We recommend to use this method when an application has a back-end and, optionally, multiple users. Users give consent to an application to access a user's resources. Users can also give consent to access an application's resources offline.

Authorization code method chart:

To initiate an authorization request, redirect a user to the proper endpoint:

https://id.adform.com/sts/connect/authorize?scope=<SCOPES>&state=<STATE>&response_type=code&client_id=<CLIENT_ID>&redirect_uri=<REDIRECT_URI>

Endpoint parameters:

Name	Description
scope	One or more space-separated scopes. Client must have access to these scopes.
state	A random client-generated string to verify that the returning user is the one who initiated the authorization. This string can be stored in a session storage before redirecting a user, and validated after the user returns.
client_id	A client (application) identifier.
redirect_uri	URI to which the user is redirected after authentication. URIs must be registered (assigned) for a client and use HTTPS.

A user will be asked to authenticate and authorize an application (to give consent).

After successful authentication, a user will be redirected to the URI provided in the redirect_uri parameter:

https://<REDIRECT_URI>?code=<AUTHORIZATION_CODE>&state=<STATE>

After a user is redirected, an application will:

• Validate a state value

• Exchange an authorization code for an access token. This will be done with a HTTP POST request in the back-end:

  POST https://id.adform.com/sts/connect/token HTTP/1.1
  Content-Type: application/x-www-form-urlencoded
  
  grant_type=authorization_code&
  code=<AUTHORIZATION_CODE>&
  client_id=<CLIENT_ID>&
  client_secret=<CLIENT_SECRET>&
  redirect_uri=<REDIRECT_URI>

  Request body parameters:

  Name	Description
  grant_type	Must be authorization_code.
  code	Authorization code received from query parameters.
  client_id	A client (application) identifier.
  client_secret	A client secret (application password).
  redirect_uri	URI to which the user is redirected to after authentication.

The response is a JSON-encoded object:

{
  "access_token": "<ACCESS_TOKEN>",
  "expires_in": <TOKEN EXPIRATION TIME IN SECONDS>,
  "token_type": "Bearer"
}

Response body parameters:

Name	Description
access_token	The requested access token. You can use it to access a secured resource, such as a web API.
expires_in	The token's duration in seconds. Once the token expires, you'll need to request it again.
token_type	The token's type. In this case, a Bearer token.

Each API request that follows must contain an access_token value in a header.

If an authorization request includes the offline_access scope, the response will include a refresh_token that you can convert to a new valid access_token.

Retrieve User Information

If your application has multiple users, you can retrieve user profile information of the authenticated user with Security & Authorization API.

You can access most Adform APIs with the EAPI scope: https://api.adform.com/scope/eapi

To retrieve a refresh token using the authorization code method, use offline_access scope.

To get an id_token or access UserInfo and other endpoints for OpenID Connect, use standard OpenID Connect scopes: openid, profile.

You can find other necessary scopes in the Required Access section in the documentation of each API as well as next to the relevant endpoints.

Once you receive an access_token, you must include it in all future API requests by adding an HTTP header.

An access token is temporary and typically expires after one hour. If you use the token after its expiration, API services will respond with the 401 HTTP code. To get a new access token, follow the directions depending on your authorization method:

You can convert an expired token to a new valid access token with an HTTP POST request:

POST /sts/connect/token HTTP/1.1
Host: id.adform.com
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token&
refresh_token=<REFRESH_TOKEN>&
client_id=<CLIENT_ID>&
client_secret=<CLIENT_SECRET>