All Adform API endpoints require authorization to ensure control of data access. To authorize with Adform APIs, you must have a valid user account.
Adform uses OAuth 2.0 as the authorization standard. With OAuth 2.0, in addition to a user account, you must register an OAuth client (application) to get an access token to use the API. Using an access token, Adform APIs can:
-
Authorize you as an end user and your OAuth client.
-
Receive and execute your request.
-
Return the requested resource.
OAuth authorization protocol uses these terms:
|
Term |
Description |
|---|---|
|
OAuth client |
An application (a web app, native desktop or mobile app, or similar) that a user uses to request access to the protected resources available through API. An OAuth client must be registered with an authorization server. |
|
User |
A person who uses a registered OAuth client to access API resources. A user can also be called a resource owner. |
|
Access token |
A string that contains information about the user and their permissions. An OAuth client uses an access token to send requests to the resource server. |
|
Scope |
An identifier for resources to which the OAuth client requires access. A user needs to send this identifier to an authorization server with a request for authentication or to get an access token. |
|
Authorization server |
An OAuth and OpenID Connect service that allows users to access APIs by authenticating a user, an OAuth client (application), and issuing tokens for that client. An authorization server can also be called an identity provider. |
OAuth 2.0 in Adform provides two 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 have an Adform account and register an OAuth client.
Important
Make sure your Adform account already has permissions and data access to the needed resources.
To register an OAuth client, contact Adform Support (technical@adform.com) with the required information depending on your authorization method.
If your application uses the client credentials authorization method, provide:
-
Client name: The username of the account on which the application works.
Note
To receive application credentials, the account must have a valid email address. We recommend having a separate user account for this workflow.
-
Use cases: A short description of your application's use cases for Adform API.
-
Scopes: A list of all the needed scopes for the application.
-
Authorization method: Specify that your application uses the client credentials authorization method.
If your application uses the authorization code method, provide:
-
Client name: The display name of your application that'll be shown on the login page, for example, Adform.
-
Logo URL: A link to a hosted version of your application's logo that'll be shown on the login page. The logo must have .jpg format and be 50x50 pixels in size.
-
Client ID prefix: The desired prefix for your client ID, added to help organize and identify clients, for example,
clientA_orregionEU_. -
Use cases: A short description of your application's use cases for Adform API.
-
Scopes: A list of all the needed scopes for the application.
-
Redirect URLs: The return URLs of your application, for example,
https://adform.com/oauth/callback. After a successful authentication, Adform API will redirect the user to one of these URLs. -
Client URL: The URL of the page with information about your application, for example, an “About us” page.
-
Email: An email address to send the authentication credentials to.
-
Authorization method: Specify that your application uses the authorization code method.
After processing your request, Adform Support team will provide your API credentials via email. To check your credentials:
-
Check your inbox for an email titled “OAuth client credentials for Adform API“. If you don’t see this email in your inbox, also check the Spam folder in case it's been filtered.
-
Click the link within the email to receive your credentials. The message should look like this:
Where:
-
Title is your OAuth client (application).
-
Username is your Client ID.
-
Password is your Client Secret.
Important
The provided link is active for seven days, but you can use it only twice. To ensure that you don’t lose this information, save your credentials before closing the window or tab.
If you lost your credentials, you must request new credentials by repeating the OAuth client registration process.
-
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.
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 |
|---|---|
|
|
Must be |
|
|
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. |
|
|
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. |
|
|
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 |
|---|---|
|
|
The requested access token. You can use it to access a secured resource, such as a web API. |
|
|
The token's duration in seconds. Once the token expires, you'll need to request it again. |
|
|
The token's type. In this case, a |
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 |
|---|---|
|
|
One or more space-separated scopes. Client must have access to these scopes. |
|
|
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. |
|
|
A client (application) identifier. |
|
|
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_typeMust be
authorization_code.codeAuthorization code received from query parameters.
client_idA client (application) identifier.
client_secretA client secret (application password).
redirect_uriURI 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 |
|---|---|
|
|
The requested access token. You can use it to access a secured resource, such as a web API. |
|
|
The token's duration in seconds. Once the token expires, you'll need to request it again. |
|
|
The token's type. In this case, a |
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.
If your application has multiple users, you can retrieve user profile information of the authenticated user with Security & Authorization API.
You can find all the necessary scopes to access Adform APIs in the Authentication section of each API article. In some APIs, scopes are also provided next to the endpoints.
To get an id_token or access UserInfo and other endpoints for OpenID Connect, use standard OpenID Connect scopes: openid, profile.
To retrieve a refresh token using the authorization code method, use offline_access scope.
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:
-
For client credentials authorization method: Obtain a new
access_token. -
For authorization code method:
-
Perform authorization method by redirecting a user to an authorization server.
-
Convert a refresh token to an access token.
-
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>