- Understanding of AEM Mobile
- Knowledge of creating and publishing content through the On-Demand Portal
- Experience with On-Demand Services APIs
- AEM Mobile
- Access to the On-Demand Services API
Adobe Experience Manager Mobile (AEM Mobile) provides a powerful On-Demand Services API which allows you to programmatically manage articles, collections, products, push notifications, and more. The API also enables third party integrations with Content Management Systems, Web-based authoring tools and Publishing Workflow Systems, many of which are available now. (See Integrating third-party systems with AEM Mobile for more details.)
Whether you want to write custom code that interfaces with the On-Demand Services API, or you want to take advantage of one of the existing integrations with third party systems, you will need valid API credentials. This article explains how API keys are used.
API credentials consist of the following items:
- API Key & Client Secret are credentials to access the API Gateway.
- Device ID and Device Token are credentials to identify the API user.
Depending on how you intend to interface via the On-Demand Services APIs, the following requirements apply.
Hosted (multi-tenant) solution
Examples: WoodWing Enterprise, WoodWing Inception, Storied, and Specle.
- Every hosted solution requires its own API Key.
- Users of the hosted solution do not need their own API Key.
- The solution owner provides users/customers with this API Key.
- Users of the hosted solution generate their own Device ID and Device Token using this API Key, and then enter these credentials into the hosted solution.
On-premise (single-tenant) solution
Examples: Adobe Experience Manager, vjoon K4, WordPress, and Drupal.
- Every customer that wants to deploy an on-premise solution requires their own API Key.
- A customer can use their API Key across multiple on-premise solutions that they implement.
- A customer needs to generate their own Device ID and Device Token and enter these credentials into their on-premise solution.
Example: Custom workflow coded by a partner or customer.
- Same requirements as the on-premise (single-tenant) case.
- Customer needs their own API Key, Device ID(s) and Device Token(s).
See the following sections for information about acquiring the API credentials that you need.
An API Key is used to gain access to the Adobe API Gateway. This gateway is a common infrastructure which is also being used by the APIs. All public APIs are behind the Adobe API Gateway. To be able to interact with services behind the API gateway, you need an API key. API keys are not tied to an individual Adobe ID, and do not expire unless Adobe revokes them. The API key consist of two parts, the name and the secret. You can think of the secret as the “password” for the API Key.
The API Key and Client Secret are sometimes referred to by other names. The following terms are equivalent:
API Key = “IMS Client ID” = “Client ID” = “Adobe API Key” = “Adobe Key”
Client Secret = “Secret” = “Adobe API Secret” = “Adobe Secret”
To request an API key, download and submit the request form PDF. For details, see Integrating third-party systems with AEM Mobile: API keys.
The recommendation is to NOT use Master Admin Adobe IDs for API access. Only use Master Admin accounts to create projects and add dedicated accounts to each of the necessary projects. For example, if you have a Drupal instance and WordPress instance and your Master Admin is firstname.lastname@example.org, your dedicated API Adobe ID for Drupal could be email@example.com (a non-Master Admin). Your dedicated Adobe ID for WordPress could be firstname.lastname@example.org (a non-Master Admin). You could then, for example, create projects called “Drupal Mag” and “WordPress Mag” with email@example.com, and add firstname.lastname@example.org and email@example.com to these projects with only the necessary roles and permissions. (Grant only the permissions to these dedicated API accounts that are needed for your intended API usage, such as “Add & Edit Content,” “Delete Content,” “View Content,” and “Publish Content.” Check the documentation for your solution for the specific permissions that are required. See Account administration for AEM Mobile.
If your request is granted, you will be given an IMS Client ID (which is your API key) and your Client Secret. Your specified Adobe ID’s will be “whitelisted” so that you can create associated Device IDs and Device Tokens as described in the next set of steps.
Once you have an API Key and Client Secret, you need to generate a Device ID and Device Token, which are used to identify the API user.
- Visit the IMS Device Token Generator (“AEX Portal”) at https://aex.aemmobile.adobe.com/, and enter your API Key/IMS Client ID.
- Sign-in using the whitelisted Adobe ID for which you want to create a Device ID/Token (one of the Adobe IDs that you specified in the API Key Request Form).
- A Device ID and Device Token will be generated and displayed. Copy and save these in a safe place.
Note that the Device ID/Device Token becomes invalid if the Adobe ID password is changed. You can think of the Device ID/Device Token as a hash of the Adobe ID and password.
Also note that the Device ID/Device Token is valid for 6 months and will become invalid if it is not used. If it is being used, it will auto-renew.
If you are connecting a supported third-party system via APIs, you will simply need to enter the API Key & Client Secret (for on-premise/single-tenant solutions only), Device ID and Device Token into the appropriate fields in the system’s setup process.
If you are accessing the API directly via your own custom code, follow the documentation in the On-Demand Services API package:
- The Device ID/Device Token are used to generate an Access Token via the Authentication API endpoint.
- The combination of the API Key and the Access Token are required for all API calls.
If you are developing a custom integration, or if you have separate production and development on-premise systems, you should use separate API Keys for development and production.
When you are developing a new system, you can request an API key with the procedure described above. Once you start deploying a system into production, you need to request an additional API key.
In the future, the Device ID and Device Token workflow will be superseded by a new technical account implementation that is managed through the On-Demand Portal. The API keys will stay in place. Instead of using a Device ID and Device Token to authenticate (and obtain an Access Token), the system will provide a ‘technical account’ that can be used to request the Access Token. To bootstrap the process, a ‘one-time-token’ will be generated. This identifier can be used only once. The consumer of the account information will exchange the one-time-token for an authentication token through an Adobe service. The resulting token can be stored for future authentication.