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 the following credentials that are required for all Platform API calls:
{ACCESS_TOKEN}
{API_KEY}
{ORG_ID}
To maintain the security of your applications and users, all requests to Adobe I/O APIs must be authenticated and authorized using standards such as OAuth and JSON Web Tokens (JWT). A JWT is used along with client-specific information to generate your personal access token.
This tutorial covers how to gather the required credentials to authenticate Platform API calls, as outlined in the following flowchart:
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:
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.
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.
Your Admin Console administrator must also add you as a user to the same product profile. See the guide on managing user groups in Admin Console for more information.
If you are following this document from the Privacy Service API guide, you can now return to that guide to generate the access credentials unique to Privacy Service.
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.
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.
From here, follow the steps outlined in the tutorial on adding an API to a project using a service account (JWT) (starting from the “Configure API” step) to finish the process.
At a certain step during the process linked above, your browser automatically downloads a private key and an associated public certificate. Note where this private key is stored on your machine, since it is required in a later step in this tutorial.
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:
{API_KEY}
(Client ID){ORG_ID}
(Organization ID)In addition to the above credentials, you also need the generated Client Secret for a future step. Select Retrieve client secret to reveal the value, and then copy it for later use.
The next step is to generate a JSON Web Token (JWT) based on your account credentials. This value is used to generate your {ACCESS_TOKEN}
credential for use in Platform API calls, which must be regenerated every 24 hours.
For the purposes of this tutorial, the steps below outline how to generate a JWT within Developer Console. However, this generation method should only be used for testing and evaluation purposes.
For regular use, the JWT must be generated automatically. For more information on how to programmatically generate JWTs, see the service account authentication guide on Adobe Developer.
Select Service Account (JWT) in the left navigation, then select Generate JWT.
In the textbox provided under Generate custom JWT, paste the contents of the private key that you previously generated when adding the Platform API to your service account. Then, select Generate Token.
The page updates to show the generated JWT, along with a sample cURL command that allows you to generate an access token. For the purposes of this tutorial, select Copy next to Generated JWT to copy the token to your clipboard.
Once you have generated a JWT, you can use it in an API call to generate your {ACCESS_TOKEN}
. Unlike the values for {API_KEY}
and {ORG_ID}
, a new token must be generated every 24 hours to continue using Platform APIs.
Request
The following request generates a new {ACCESS_TOKEN}
based on the credentials provided in the payload. This endpoint only accepts form data as its payload, and therefore it must be given a Content-Type
header of multipart/form-data
.
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}'
Property | Description |
---|---|
{API_KEY} |
The {API_KEY} (Client ID) that you retrieved in a previous step. |
{SECRET} |
The client secret that you retrieved in a previous step. |
{JWT} |
The JWT that you generated in a previous step. |
You can use the same API key, client secret, and JWT to generate a new access token for each session. This allows you to automate access token generation in your applications.
Response
{
"token_type": "bearer",
"access_token": "{ACCESS_TOKEN}",
"expires_in": 86399992
}
Property | Description |
---|---|
token_type |
The type of token being returned. For access tokens, this value is always bearer . |
access_token |
The generated {ACCESS_TOKEN} . This value, prefixed with the word Bearer , is required as the Authentication header for all Platform API calls. |
expires_in |
The number of milliseconds remaining until the access token expires. Once this value reaches 0, a new access token must be generated to continue using Platform APIs. |
Once you have gathered all three required credentials, you can try to make the following API call. This call lists all standard Experience Data Model (XDM) classes available to your organization.
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"
}
]
}
Postman is a popular tool that allows developers to explore and test RESTful APIs. This Medium post describes how you can set up Postman to automatically perform JWT authentication and use it to consume Platform APIs.
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.