Authenticate and access Experience Platform APIs

This document provides a step-by-step tutorial for gaining access to an Adobe Experience Platform developer account in order to make calls to Experience Platform APIs. At the end of this tutorial, you will have generated or collected the following credentials that are required as headers in all Platform API calls:

To maintain the security of your applications and users, all requests to Experience Platform APIs must be authenticated and authorized using standards such as OAuth.

This tutorial covers how to gather the required credentials to authenticate Platform API calls, as outlined in the flowchart below. You can gather most of the required credentials in the initial one-time setup. The access token, however, must be refreshed every 24-hours.

Prerequisites prerequisites

In order to successfully make calls to Experience Platform APIs, you must have the following:

You must also have an Adobe ID to complete this tutorial. If you do not have an Adobe ID, you can create one using the following steps:

Gain developer and user access for Experience Platform gain-developer-user-access

Before creating integrations on Adobe Developer Console, your account must have developer and user permissions for an Experience Platform product profile in Adobe Admin Console.

Gain developer access gain-developer-access

Contact an Admin Console administrator in your organization to add you as a developer to an Experience Platform product profile using the Admin Console. See the Admin Console documentation for specific instructions on how to manage developer access for product profiles.

Once you are assigned as a developer, you can start creating integrations in Adobe Developer Console. These integrations are a pipeline from external apps and services to Adobe APIs.

Gain user access gain-user-access

Your Admin Console administrator must also add you as a user to the same product profile. With user access, you can see in the UI the outcome of the API operations that you perform.

See the guide on managing user groups in Admin Console for more information.

Generate an API key (client ID) and organization ID generate-credentials

After you have been given developer and user access to Platform through Admin Console, the next step is to generate your {ORG_ID} and {API_KEY} credentials in Adobe Developer Console. These credentials only need to be generated once and can be reused in future Platform API calls.

Add Experience Platform to a project add-platform-to-project

Go to Adobe Developer Console and sign in with your Adobe ID. Next, follow the steps outlined in the tutorial on creating an empty project in the Adobe Developer Console documentation.

Once you have created a new project, select Add API on the Project Overview screen.

The Add an API screen appears. Select the product icon for Adobe Experience Platform, then choose Experience Platform API before selecting Next.

Select the OAuth Server-to-Server authentication type select-oauth-server-to-server

Next, select the OAuth Server-to-Server authentication type to generate access tokens and access the Experience Platform API.

Select the product profiles for your integration select-product-profiles

In the Configure API screen, select AEP-Default-All-Users.

Select Save configured API when you are ready.

A walkthrough of the steps described above to set up an integration with the Experience Platform API is also available in the video tutorial below:

Gather credentials gather-credentials

Once the API has been added to the project, the Experience Platform API page for the project displays the following credentials that are required in all calls to Experience Platform APIs:

Generate an access token generate-access-token

The next step is to generate an {ACCESS_TOKEN} credential for use in Platform API calls. Unlike the values for {API_KEY} and {ORG_ID}, a new token must be generated every 24 hours to continue using Platform APIs. Select Generate access token, as shown below.

[Deprecated]{class="badge negative"} Generate a JSON Web Token (JWT) jwt

curl -X POST https://ims-na1.adobelogin.com/ims/exchange/jwt \
  -H 'Content-Type: multipart/form-data' \
  -F 'client_id={API_KEY}' \
  -F 'client_secret={SECRET}' \
  -F 'jwt_token={JWT}'

{
  "token_type": "bearer",
  "access_token": "{ACCESS_TOKEN}",
  "expires_in": 86399992
}

Test access credentials test-credentials

Once you have gathered all three required credentials - access token, API key, and Organization ID - , you can try to make the following API call. This call lists all standard Experience Data Model (XDM) classes available to your organization. Import and execute the call in Postman.

Request

curl -X GET https://platform.adobe.io/data/foundation/schemaregistry/global/classes \
  -H 'Accept: application/vnd.adobe.xed-id+json' \
  -H 'Authorization: Bearer {{ACCESS_TOKEN}}' \
  -H 'x-api-key: {{API_KEY}}' \
  -H 'x-gw-ims-org-id: {{ORG_ID}}'

Response

If your response is similar to the one shown below, then your credentials are valid and working. (This response has been truncated for space.)

{
  "results": [
    {
        "title": "XDM ExperienceEvent",
        "$id": "https://ns.adobe.com/xdm/context/experienceevent",
        "meta:altId": "_xdm.context.experienceevent",
        "version": "1"
    },
    {
        "title": "XDM Individual Profile",
        "$id": "https://ns.adobe.com/xdm/context/profile",
        "meta:altId": "_xdm.context.profile",
        "version": "1"
    }
  ]
}

Get the necessary attribute-based access control permissions get-abac-permissions

To access or modify several resources within Experience Platform, you must have the appropriate access control permissions. System administrators can grant you the permissions you need. Get more information in the section about managing API credentials for a role.

Detailed information about how a system administrator can grant the required permissions to access Platform resources through the API is also available in the video tutorial below:

Use Postman to authenticate and test API calls use-postman

Postman is a popular tool that allows developers to explore and test RESTful APIs. You can use Experience Platform Postman collections and environments to speed up your work with Experience Platform APIs. Read more about using Postman in Experience Platform and getting started with collections and environments.

Detailed information about using Postman with Experience Platform collections and environments is also available in the video tutorials below:

Download and import a Postman environment to use with Experience Platform APIs

Use a Postman collection to generate access tokens

Download the Identity Management Service Postman collection and watch the video below to learn how to generate access tokens.

Download Experience Platform API Postman collections and interact with the APIs

System administrators: Grant developer and API access control with Experience Platform permissions grant-developer-and-api-access-control

Before creating integrations on Adobe Developer Console, your account must have developer and user permissions for an Experience Platform product profile in Adobe Admin Console.

Add developers to product profile add-developers-to-product-profile

Go to Admin Console and sign in with your Adobe ID.

Select Products, then select Adobe Experience Platform from the list of products.

From the Product Profiles tab, select AEP-Default-All-Users. Alternatively, use the search bar to search for the product profile by entering the name.

Select the Developers tab, then select Add Developer.

Enter the developer’s Email or username. A valid Email or username will display the developer details. Select Save.

The developer has been successfully added and appears on the Developers tab.

Assign API to a role

A system admin can assign APIs to roles in the Experience Platform UI.

Select Permissions and the role you want to add the API to. Select the API credentials tab, then select Add API credentials.

Select the API you would like to add to the role then select Save.

You are returned to the API credentials tab, where the newly added API is listed.

Additional resources additional-resources

Refer to the additional resources linked below for further help getting started with Experience Platform APIs

Next steps next-steps

By reading this document, you have gathered and successfully tested your access credentials for Platform APIs. You can now follow along with the example API calls provided throughout the documentation.

In addition to the authentication values you have gathered in this tutorial, many Platform APIs also require a valid {SANDBOX_NAME} to be provided as a header. See the sandboxes overview for more information.