DocumentationAEMAEM TutorialsAEM as a Cloud Service Tutorials

Set up OpenAPI-based AEM APIs

Last update: Fri Dec 12 2025 00:00:00 GMT+0000 (Coordinated Universal Time)
  • Applies to:
  • Experience Manager as a Cloud Service

CREATED FOR:

  • Beginner
  • Developer
  • Leader

Learn how to set up your AEM as a Cloud Service environment to enable access to the OpenAPI-based AEM APIs.

In this example, the AEM Assets API using the Server-to-Server authentication method is used to demonstrate the OpenAPI-based AEM APIs setup process. The similar steps can be followed to setup other OpenAPI-based AEM APIs.

https://video.tv.adobe.com/v/3457510?quality=12&learn=on

The high-level setup process involves the following steps:

  1. Modernization of AEM as a Cloud Service environment.
  2. Enable AEM APIs access.
  3. Create Adobe Developer Console (ADC) Project.
  4. Configure ADC Project.
  5. Configure the AEM instance to enable ADC Project communication.

Prerequisites

  • Access to Cloud Manager and AEM as a Cloud Service environment
  • Access to Adobe Developer Console (ADC).
  • AEM project to add or update the API configuration in the api.yaml file.

Modernization of AEM as a Cloud Service environment modernization-of-aem-as-a-cloud-service-environment

The modernization of AEM as a Cloud Service environment is a one-time per environment activity that involves the following steps. If you have already modernized your AEM as a Cloud Service environment, you can skip this step.

  • Update to the AEM Release 2024.10.18459.20241031T210302Z or later.
  • Add new Product Profiles to it, if the environment was created before the release 2024.10.18459.20241031T210302Z.

Update AEM instance update-aem-instance

  • To update the AEM instance, after logging in to the Adobe Cloud Manager, navigate to the Environments section, select the ellipsis icon next to the environment name and select Update option.

Update AEM instance

  • Then click the Submit button and run the suggested Fullstack Pipeline.

Select latest AEM release version

In my case, the Fullstack Pipeline is named Dev :: Fullstack-Deploy, and the AEM environment is called wknd-program-dev. Your names may be different.

Add new Product Profiles add-new-product-profiles

  • To add new Product Profiles to the AEM instance, in the Adobe Cloud Manager’s Environments section, select the ellipsis icon next to the environment name and select the Add Product Profiles option.

Add new Product Profiles

  • Review the newly added Product Profiles by clicking on the ellipsis icon next to the environment name and selecting Manage Access > Author Profiles.

  • The Admin Console window displays the newly added Product Profiles. Depending on your AEM entitlements like AEM Assets, AEM Sites, AEM Forms, etc., you may see different Product Profiles. For example, in my case, I have AEM Assets and Sites entitlements, so I see the following Product Profiles.

Review new Product Profiles

  • The above steps complete the modernization of the AEM as a Cloud Service environment.

Enable AEM APIs access enable-aem-apis-access

The presence of the new Product Profiles enable OpenAPI-based AEM API access in the Adobe Developer Console (ADC). Without these Product Profiles, you can not set up the OpenAPI-based AEM APIs in the Adobe Developer Console (ADC).

The newly added Product Profiles are associated with the Services that represent AEM user groups with predefined Access Control Lists (ACLs). The Services are used to control the level of access to the AEM APIs. You can also select or deselect the Services associated with the Product Profile to reduce or increase the level of access.

Review the association by clicking on the View Details icon next to the Product Profile name. In the following screenshot, you can see the association of the AEM Sites Content Managers - author - Program XXX - Environment XXX Product Profile with the AEM Sites Content Managers Service. Review other Product Profiles and their associations with the Services.

Review services associated with Product Profile

Enable AEM Assets APIs access enable-aem-assets-apis-access

In this example, the AEM Assets API is used to demonstrate the OpenAPI-based AEM APIs setup process. However, by default, the AEM Assets API Users Service is not associated with any Product Profile. You need to associate it with the desired Product Profile.

Let’s associate it with the newly added AEM Assets Collaborator Users - author - Program XXX - Environment XXX Product Profile or any other Product Profile that you want to use for AEM Assets API access.

Associate AEM Assets API Users Service with Product Profile

Enable Server-to-Server authentication

To enable the Server-to-Server authentication for the desired OpenAPI-based AEM APIs, the user setting up integration using the Adobe Developer Console (ADC) must be added as a Developer to the Product Profile where the Service is associated.

For example, to enable the Server-to-Server authentication for the AEM Assets API, the user must be added as a Developer to the AEM Assets Collaborator Users - author - Program XXX - Environment XXX Product Profile.

Associate Developer to Product Profile

After this association, the ADC Project’s Asset Author API can set up the desired Server-to-Server authentication and associate the authentication account from the ADC Project (created in the next step) with the Product Profile.

IMPORTANT
The above step is critical to enable the Server-to-Server authentication for the desired AEM API. Without this association, the AEM API cannot be used with the Server-to-Server authentication method.

By performing all the above steps, you have prepared the AEM as a Cloud Service environment to enable OpenAPI-based AEM APIs access. Next, you need to create the Adobe Developer Console (ADC) Project to set up the OpenAPI-based AEM APIs.

Create Adobe Developer Console (ADC) Project adc-project

The Adobe Developer Console (ADC) project is used to set up the OpenAPI-based AEM APIs. Recall that the Adobe Developer Console (ADC) is the developer hub for accessing Adobe APIs, SDKs, real-time events, serverless functions, and more.

The ADC Project is used to add the desired APIs, set up its authentication, and associate the authentication account with the Product Profile.

To create an ADC Project:

  1. Login to the Adobe Developer Console using your Adobe ID.

    Adobe Developer Console

  2. From the Quick Start section, click on the Create new project button.

    Create new project

  3. It creates a new project with the default name.

    New project created

  4. Edit the project name by clicking the Edit project button in the top right corner. Provide a meaningful name and click Save.

    Edit project name

Configure ADC Project configure-adc-project

After creating the ADC Project, you have to add the desired AEM APIs, set up its authentication, and associate the authentication account with the Product Profile.

In this case, the AEM Assets API is used to demonstrate the OpenAPI-based AEM APIs setup process. However, you can follow the similar steps to add other OpenAPI-based AEM APIs like AEM Sites API, AEM Forms API, etc. The AEM entitlements determine the available APIs in the Adobe Developer Console (ADC).

  1. To add AEM APIs, click on the Add API button.

    Add API

  2. In the Add API dialog, filter by Experience Cloud and select the desired AEM API. For example, in this case, the Asset Author API is selected.

    Add AEM API

    note tip
    TIP
    If the desired AEM API card is disabled and Why is this disabled? information shows the License required message one of the reasons could be that you have NOT modernized your AEM as a Cloud Service environment, see Modernization of AEM as a Cloud Service environment for more information.

  3. Next, in the Configure API dialog, select the desired authentication option. For example, in this case, the Server-to-Server authentication option is selected.

    Select authentication

    The Server-to-Server authentication is ideal for backend services needing API access without user interaction. The Web App and Single Page App authentication options are suitable for applications needing API access on behalf of users. See Difference between OAuth Server-to-Server vs Web App vs Single Page App credentials for more information.

    note tip
    TIP
    If you do not see the Server-to-Server authentication option, it means that the user setting up the integration is not added as a Developer to the Product Profile where the Service is associated. See Enable Server-to-Server authentication for more information.

  4. If needed, you can rename the API for easier identification. For demo purposes, the default name is used.

    Rename credential

  5. In this case, the authentication method is OAuth Server-to-Server so you need to associate the authentication account with the Product Profile. Select the AEM Assets Collaborator Users - author - Program XXX - Environment XXX Product Profile and click Save.

    Select Product Profile

  6. Review the AEM API and authentication configuration.

    AEM API configuration

    Authentication configuration

If you choose the OAuth Web App or OAuth Single Page App authentication method, the Product Profile association is not prompted but application redirect URI is required. The application redirect URI is used to redirect the user to the application after authentication with an authorization code. The relevant use cases tutorials outline such authentication specific configurations.

Configure the AEM instance to enable ADC Project communication configure-aem-instance

Next, you need to configure the AEM instance to enable above ADC Project communication. With this configuration, the ADC Project’s ClientID can NOT communicate with the AEM instance and results in a 403 Forbidden error. Think of this configuration as a firewall rule to allow only the allowed ClientIDs to communicate with the AEM instance.

Let’s follow the steps to configure the AEM instance to enable above ADC Project communication.

  1. On your local machine, navigate to the AEM project (or clone it if you haven’t already) and locate the config folder.

  2. In AEM Project, locate or create the api.yaml file from the config folder. In my case, the AEM WKND Sites Project is used to demonstrate the OpenAPI-based AEM APIs setup process.

    Locate API YAML

  3. Add the following configuration to the api.yaml file to allow the ADC Project’s ClientID to communicate with the AEM instance.

    code language-yaml 
    kind: "API"
version: "1.0"
metadata:
    envTypes: ["dev", "stage", "prod"]
data:
    allowedClientIDs:
        author:
        - "<ADC Project's Credentials ClientID>"

    Replace <ADC Project's Credentials ClientID> with the actual ClientID of the ADC Project’s Credentials value. The API endpoint that is used in this tutorial is available only on the author tier, but for other APIs, the yaml config can also have a publish or preview node.

    note caution
    CAUTION
    For demo purposes, the same ClientID is used for all environments. It is recommended to use separate ClientID per environment (dev, stage, prod) for better security and control.

  4. Commit the config changes and push the changes to the remote Git repository the Cloud Manager pipeline is connected to.

  5. Deploy the above changes using the Config Pipeline in the Cloud Manager.

    Deploy YAML

Note that the api.yaml file can also be installed in an RDE, using command line tooling. This is useful for testing the configuration changes before deploying them to the production environment.

Next steps

Once the AEM instance is configured to enable ADC Project communication, you can start using the OpenAPI-based AEM APIs. Learn how to use the OpenAPI-based AEM APIs using different OAuth authentication methods:

Invoke API using Server-to-Server authentication

Invoke API using Server-to-Server authentication

Learn how to invoke OpenAPI-based AEM APIs from a custom NodeJS application using OAuth Server-to-Server authentication.

Learn more

Invoke API using Web App authentication

Invoke API using Web App authentication

Learn how to invoke OpenAPI-based AEM APIs from a custom web application using OAuth Web App authentication.

Learn more

Invoke API using Single Page App authentication

Invoke API using Single Page App authentication

Learn how to invoke OpenAPI-based AEM APIs from a custom Single Page App (SPA) using OAuth 2.0 PKCE flow.

Learn more

recommendation-more-help
4859a77c-7971-4ac9-8f5c-4260823c6f69