Getting Started with REST APIs
Information about general requirements, authentication, optional query parameters, request URLs, and other references.
API Requirements and Recommendations
Things you must and should do when working with the Audience Manager APIs.
Note the following when working with Audience Manager API code:
- Request parameters: all request parameters are required unless specified otherwise.
- Request headers: when using Adobe Developer tokens, you must provide the
x-api-key
header. You can get your API key by following the instructions in the Service Account Integration page. - JSON content type: Specify
content-type: application/json
andaccept: application/json
in your code. - Requests and responses: Send requests as a properly formatted JSON object. Audience Manager responds with JSON formatted data. Server responses can contain requested data, a status code, or both.
- Access: Your Audience Manager consultant will provide you with a client ID and key that lets you make API requests.
- Documentation and code samples: Text in italics represents a variable that you provide or pass in when making or receiving API data. Replace italicised text with your own code, parameters, or other required information.
Authentication
The Audience Manager REST APIs support two authentication methods.
- JWT (Service Account) Authentication using Adobe Developer. Adobe Developer is Adobe’s developer ecosystem and community. It includes APIs for all Adobe products. This is the recommended way of setting up and using Adobe APIs.
- OAuth Authentication (deprecated). While this method is deprecated, customers with existing OAuth integrations can continue using this method.
JWT (Service Account) Authentication using Adobe Developer
Adobe Developer Overview
Adobe Developer is Adobe’s developer ecosystem and community. It includes APIs for all Adobe products.
This is the recommended way of setting up and using Adobe APIs.
Prerequisites
Before you can configure JWT authentication, make sure you have access to the Adobe Developer Console in Adobe Developer. Contact your organization administrator for access requests.
Authentication
Follow the steps below to configure JWT (Service Account) authentication using Adobe Developer:
- Log in to the Adobe Developer Console.
- Follow the steps in Service Account Connection.
- During Step 2: Add an API to your project using Service Account authentication, choose the Audience Manager API option.
- Try out the connection by making your first API call based on the instructions from Step 3.
Technical account RBAC permissions
If your Audience Manager account uses Role-based Access Control, you must create an Audience Manager technical user account and add it to the Audience Manager RBAC group that will make the API calls.
Follow the steps below to create a technical user account and add it to an RBAC group:
-
Make a
GET
call tohttps://aam.adobe.io/v1/users/self
. The call will create a technical user account that you can see in the Admin Console, in the Users page. -
Log in to your Audience Manager account and add the technical user account to the user group that will make the API calls.
OAuth Authentication (Deprecated)
The Audience Manager REST API follows OAuth 2.0 standards for token authentication and renewal. The sections below describe how to authenticate and start working with the APIs.
Create a Generic API User
We recommend you create a separate, technical user account for working with the Audience Manager APIs. This is a generic account that is not tied to or associated with a specific user in your organization. This type of API user account helps you accomplish 2 things:
- Identify what service is calling the API (e.g., calls from your apps that use our APIs or from other tools that make API requests).
- Provide uninterrupted access to the APIs. An account tied to a specific person may be deleted when they leave your company. This will prevent you from working with the available API code. A generic account that’s not tied to a particular employee helps you avoid this problem.
As an example or use case for this type of account, let’s say you want to change a lot of segments at once with the Bulk Management Tools. Well, to do this, your user account needs API access. Rather than add permissions to a specific user, create a non-specific, API user account that has the appropriate credentials, key, and secret to make API calls. This is also useful if you develop your own applications that use the Audience Manager APIs.
Work with your Audience Manager consultant to set up a generic, API-only user account.
Password Authentication Workflow
Password authentication secure access our REST API. The steps below outline the workflow for password authentication from a JSON client in your browser.
Step 1: Request API Access
Contact your Partner Solutions manager. They will provide you with an API client ID and secret. The ID and secret authenticate you to the API.
Note: If you’d like to receive a refresh token, specify that when you request API access.
Step 2: Request the Token
Pass in a token request with your preferred JSON client. When you build the request:
- Use a
POST
method to callhttps://api.demdex.com/oauth/token
. - Convert your client ID and secret to a base-64 encoded string. Separate the ID and secret with a colon during the conversion process. For example, the credentials
testId : testSecret
convert todGVzdElkOnRlc3RTZWNyZXQ=
. - Pass in the HTTP headers
Authorization:Basic <base-64 clientID:clientSecret>
andContent-Type: application/x-www-form-urlencoded
. For example, your header could look like this:Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
- Set up the request body as follows:
grant_type=password&username=<your-AudienceManager-user-name>&password=<your-AudienceManager-password>
Step 3: Receive the Token
The JSON response contains your access token. The response should look like this:
{
"access_token": "28fed402-eafd-456c-9341-ac753f25bbbc",
"token_type": "bearer",
"refresh_token": "b27122c0-b0c7-4b39-a71b-1547a3b3b88e",
"expires_in": 21922,
"scope": "read write"
}
The expires_in
key represents the number of seconds until the access token expires. As best practice, use short expiration times to limit exposure if the token is ever exposed.
Refresh Token
Refresh tokens renew API access after the original token expires. If requested, the response JSON in the password workflow includes a refresh token. If you don’t receive a refresh token, create a new one through the password authentication process.
You can also use a refresh token to generate a new token before the existing access token expires.
If your access token has expired, you receive a 401 Status Code
and the following header in the response:
WWW-Authenticate: Bearer realm="oauth", error="invalid_token", error_description="Access token expired: <token>"
The following steps outline the workflow for using a refresh token to create a new access token from a JSON client in your browser.
Step 1: Request the New Token
Pass in a refresh token request with your preferred JSON client. When you build the request:
- Use a
POST
method to callhttps://api.demdex.com/oauth/token
. - Convert your client ID and secret to a base-64 encoded string. Separate the ID and secret with a colon during the conversion process. For example, the credentials
testId : testSecret
convert todGVzdElkOnRlc3RTZWNyZXQ=
. - Pass in the HTTP headers
Authorization:Basic <base-64 clientID:clientSecret>
andContent-Type: application/x-www-form-urlencoded
. For example, your header could look like this:Authorization: Basic dGVzdElkOnRlc3RTZWNyZXQ=
Content-Type: application/x-www-form-urlencoded
- In the request body, specify the
grant_type:refresh_token
and pass in the refresh token you received in your previous access request. The request should look like this:grant_type=refresh_token&refresh_token=b27122c0-b0c7-4b39-a71b-1547a3b3b88e
Step 2: Receive the New Token
The JSON response contains your new access token. The response should look like this:
{
"access_token": "4fdfc261-2ffc-4fb7-8dbd-64221714c45f",
"token_type": "bearer",
"refresh_token": "295fa487-1825-4caa-a715-80b81ac17dae",
"expires_in": 21922,
"scope": "read write"
}
Authorization Code and Implicit Authentication
The Audience Manager REST API supports authorization code and implicit authentication. To use these access methods, your users need to log in to https://api.demdex.com/oauth/authorize
to get access and refresh tokens.
Make Authenticated API Requests
Requirements for calling API methods after you receive an authentication token.
To make calls against the available API methods:
- In the
HTTP
header, setAuthorization: Bearer <token>
. - When using JWT (Service Account) Authentication, you need to provide the
x-api-key
header, which will be the same as yourclient_id
. You can get yourclient_id
from the Adobe Developer integration page. - Call the required API method.
Optional API Query Parameters
Set the optional parameters available to methods that return all properties for an object.
You can use these optional parameters with API methods that return all properties for an object. Set these options in the request string when passing that query in to the API.
page
pageSize
sortBy
descending
ascending
is default.search
GET https://aam.adobe.io/v1/models/?search=Test
. You can search on any value returned by a “get all” method.folderId
permissions
Returns a list of segments based on the specified permission. READ
is default. Permissions include:
READ
: Return and view information about a segment.WRITE
: UsePUT
to update a segment.CREATE
: UsePOST
to create a segment.DELETE
: Delete a segment. Requires access to underlying traits, if any. For example, you’ll need rights to delete the traits that belong to a segment if you want to remove it.
Specify multiple permissions with separate key-value pairs. For example, to return a list of segments with READ
and WRITE
permissions only, pass in "permissions":"READ"
, "permissions":"WRITE"
.
includePermissions
true
to return your permissions for the segment. Default is false
.A Note About Page Options
When page information is not specified, the request returns plain JSON results in an array. If page information is specified, then the returned list is wrapped in a JSON object that contains information about the total result and current page. Your sample request using page options could look similar to this:
GET https://aam.adobe.io/v1/models/?page=1&pageSize=2&search=Test
API URLs
URLs for requests, staging and production environments, and versions.
Request URLs
The following table lists the request URLs used to pass in API requests, by method.
Depending on the authentication method that you use, you need to adjust your request URLs according to the tables below.
Request URLs for JWT Authentication
https://aam.adobe.io/v1/models/
https://aam.adobe.io/v1/datasources/
https://aam.adobe.io/v1/signals/derived/
https://aam.adobe.io/v1/destinations/
https://aam.adobe.io/v1/partner-sites/
https://aam.adobe.io/v1/folders/traits /
Segments:
https://aam.adobe.io/v1/folders/segments /
https://aam.adobe.io/v1/schemas/
https://aam.adobe.io/v1/segments/
https://aam.adobe.io/v1/traits/
https://aam.adobe.io/v1/customer-trait-types
https://aam.adobe.io/v1/taxonomies/0/
Request URLs for OAuth Authentication (Deprecated)
https://api.demdex.com/v1/models/
https://api.demdex.com/v1/datasources/
https://api.demdex.com/v1/signals/derived/
https://api.demdex.com/v1/destinations/
https://api.demdex.com/v1/partner-sites/
https://api.demdex.com/v1/folders/traits /
Segments:
https://api.demdex.com/v1/folders/segments /
https://api.demdex.com/v1/schemas/
https://api.demdex.com/v1/segments/
https://api.demdex.com/v1/traits/
https://api.demdex.com/v1/customer-trait-types
https://api.demdex.com/v1/taxonomies/0/
Environments
The Audience Manager APIs provide access to different working environments. These environments help you test code against separate databases without affecting live, production data. The following table lists the available API environments and corresponding resource hostnames.
Depending on the authentication method that you use, you need to adjust your environment URLs according to the table below.
https://aam.adobe.io/...
https://api.demdex.com/...
https://aam-beta.adobe.io/...
https://api-beta.demdex.com/...
Versions
New versions of these APIs are released on a regular schedule. A new release increments the API version number. The version number is referenced in the request URL as v<version number>
as shown in the following example:
https://<host>/v1/...
Response Codes Defined
HTTP
status codes and response text returned by the Audience Manager REST API.
200
OK
201
Created
PUT
and POST
requests.204
No Content
400
Bad Request
403
Forbidden
404
Not Found
409
Conflict
500
Server Error