> ## Documentation Index > Fetch the complete documentation index at: https://docs.gradial.com/llms.txt > Use this file to discover all available pages before exploring further. # AEM OpenAPI > Connect Gradial to AEM as a Cloud Service with Adobe OpenAPI-based APIs. ## Overview The AEM OpenAPI integration lets Gradial use Adobe's OpenAPI-based AEM APIs for AEM as a Cloud Service. Through it, Gradial can search, read, create, copy, and update Content Fragments, stage Content Fragment changes in Launches, create DAM folders, search assets, and use Adobe's page-management APIs where your organization has them. > [!NOTE] > > This guide covers AEM as a Cloud Service. Adobe offers a subset of these APIs on AEM 6.5 LTS (SP2 or later), but not on earlier AEM 6.x versions. For AEM 6.5 or Adobe Managed Services, use the [AEM 6.5](https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/aem/aem-on-prem.md) or [AMS / AEM as a Cloud Service](https://docs.gradial.com/docs/integrations-administration-and-setup/integrations/aem/aem-cloud.md) guides. The operations available in Gradial also depend on the Adobe API products, permissions, and Gradial capabilities enabled for your organization. Choose the authentication model that matches your use case: > **Server-to-server** > > Use a technical account for automated work that does not need to be attributed to an individual AEM user. > **Authenticate as user** > > Each Gradial user signs in through Adobe. AEM applies that user's permissions and attributes changes to that user. An AEM OpenAPI integration covers Content Fragment, Launch, folder, asset search, and page-management work on its own. Other AEM work, such as page previews and asset uploads, needs a legacy AEM integration for the same author environment. See [Capability boundaries](#capability-boundaries). ## Before you start You need: * An AEM as a Cloud Service author URL, such as `https://author-p12345-e67890.adobeaemcloud.com`. * Access to Adobe Developer Console and the Adobe Admin Console for the target IMS organization. * An AEM project repository and permission to run a Cloud Manager config pipeline. * A Gradial organization admin. Only admins can add, edit, or remove organization integrations. If **AEM OpenAPI** is not available in the Gradial integration catalog, contact your Gradial representative to enable it for your organization. ### Ensure AEM API access is enabled Adobe Developer Console exposes AEM API products only after the target AEM as a Cloud Service environment is modernized and its required Product Profile services are enabled. If an AEM API card is unavailable or disabled in Developer Console, have the Cloud Manager and Adobe Admin Console owners update the environment as needed, add the required Product Profiles, and enable the related service before creating the credential. Adobe documents this as a one-time preparation step per environment in its [OpenAPI setup guide](https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/aem-apis/openapis/setup). ## Roles and coordination An AEM OpenAPI rollout usually involves more than one administrator. Assign each responsibility before starting: | Responsibility | Typical owner | | - | - | | Create the Adobe Developer Console project and credential | Adobe Developer Console administrator or developer | | Assign product profiles and AEM permissions | Adobe Admin Console and AEM administrator | | Add `config/api.yaml` and run the config pipeline | AEM repository maintainer and Cloud Manager deployment owner | | Create the Gradial integration and mappings | Gradial organization admin | | Connect individual users for user authentication | Each Gradial user who will perform AEM work | For production, agree on the mapped site and DAM roots before credentials are created. That gives the AEM administrator a clear least-privilege permission boundary and prevents a broad technical account from being needed later. ## Configure Adobe ### 1. Create an Adobe Developer Console project In [Adobe Developer Console](https://developer.adobe.com/console/projects), create a project for the target AEM environment. Add the Adobe API products required for the work Gradial will perform: | Use case | Adobe API product | | - | - | | DAM folders and assets | **AEM Assets Author API** | | Content Fragments, and validating mapped Site paths | **AEM CS Sites Content Management** | Content Fragment Launches and page management use additional AEM APIs: Adobe's Launches API and its experimental page-management APIs. Enable them in the project if you plan to use those capabilities. When a user-authenticated connection lacks one, Gradial names the missing permission on **Reconnect AEM**. Adobe may expose different API products to different organizations. Add only the products that your organization is entitled to use and that match the capabilities you need. In Adobe Developer Console, use **Add to Project -> API** to add each required product. If the product does not appear, the Adobe organization may not be entitled to it yet. Contact Adobe support or the organization's Adobe administrator before continuing. You do not configure OAuth scopes in Gradial. Gradial requests the scopes each operation needs, and Adobe grants only the scopes for API products attached to the project. If an API product is missing, requests that need it fail with Adobe's "The access token is missing required scopes" error. ### 2. Choose and create the credential Use one of the following credential types in the same Adobe Developer Console project: | Gradial authentication type | Adobe credential | Use when | | - | - | - | | **Server-to-server** | OAuth Server-to-Server | Gradial should operate as a technical account. | | **Authenticate as user** | OAuth Web App | AEM must apply each person's permissions and record their identity on changes. | Retain the credential's **Client ID** and **Client Secret**. Do not put the secret in source control. > [!WARNING] > > The Client ID is safe to place in AEM's `api.yaml` allowlist. The Client Secret is not. Keep it only in Adobe Developer Console and the Gradial integration form. ### 3. Grant the right Adobe and AEM permissions For server-to-server access, associate the credential with an Adobe product profile that has the minimum AEM permissions required for the mapped content paths. For user authentication, each person who clicks **Connect AEM** must have the appropriate Adobe product-profile and AEM permissions. To create a Server-to-Server credential, the person configuring the Adobe Developer Console project must be an Adobe organization administrator or a Developer on the Product Profile where the required AEM API service is enabled. Otherwise, Adobe does not offer that credential option for the API. Adobe's default API product profiles can be read-only. If reads work but creates, updates, or deletes return `403 Forbidden`, the product profile needs write permission. Start with a non-production environment and reduce permissions to the smallest set that works. Write, publish, and launch permissions should be granted only when required. For a least-privilege configuration, grant access only to the mapped AEM paths. Typical boundaries are a site root under `/content`, a DAM root under `/content/dam`, and any Content Fragment or Launch paths needed by the selected workflow. A publish or promotion workflow may require additional permission beyond ordinary content authoring. ### 4. Allowlist the Adobe Client ID in AEM Every credential's Client ID must be allowlisted in the AEM environment. Add an `api.yaml` file under a top-level `config` directory in the AEM project repository: ```yaml theme={null} kind: "API" version: "1" data: allowedClientIDs: author: - "" ``` Use the Client ID for the actual OAuth Server-to-Server or OAuth Web App credential. It is not the IMS organization ID or a technical-account email address. Gradial calls the author tier only, so it needs an `author` entry. Adobe also accepts `publish` and `preview` lists for other clients. Adobe states that this YAML file is the only supported way to configure the allowlist; environment variables are not supported for it. Deploy this file with a Cloud Manager [config pipeline](https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/operations/config-pipeline) (choose **Targeted Deployment** when creating the pipeline). Full Stack and Web Tier pipelines do not deploy this configuration. For a Rapid Development Environment, install it with `aio aem:rde:install -t env-config ./config`. For additional environments or credentials, add their Client IDs to the allowlist and deploy the configuration to each environment. > [!WARNING] > > A valid token alone is not enough. Until the Client ID is allowlisted and the config pipeline has deployed it to that environment, AEM rejects every OpenAPI request from the credential with `403 Forbidden` and the message "IMS Client ID not allowlisted. Allowlist the Client ID using the Configuration Pipeline." > [!NOTE] > > Adobe recommends separate Client IDs for development, stage, and production so access can be scoped and revoked independently. ### 5. Plan environments deliberately Use separate Adobe credentials and separate Gradial integrations for each AEM environment. This keeps development credentials out of production and lets you remove one environment's access without disrupting the others. | Environment | Adobe credential | AEM allowlist | Gradial integration | | - | - | - | - | | Development | Development Client ID | Development author environment | Development AEM OpenAPI integration | | Stage | Stage Client ID | Stage author environment | Stage AEM OpenAPI integration | | Production | Production Client ID | Production author environment | Production AEM OpenAPI integration | ## Adobe-side checklist Before entering credentials in Gradial, confirm all of the following: * The required Adobe API products are attached to the Developer Console project. * The chosen OAuth credential has a Client ID and Client Secret. * The credential or each user has the intended AEM permissions, including write permission if Gradial will make changes. * The credential's Client ID is in `config/api.yaml` under the `author` allowlist. * A Cloud Manager config pipeline has deployed the allowlist to the intended environment. * The AEM author URL and the intended Site and DAM roots are known. ## Add the integration in Gradial The **Add AEM OpenAPI integration** dialog has two tabs, **Basic** and **Mappings**. **1. Open the dialog** In Gradial, go to **Settings -> Integrations**, select **Connect integration**, then select **AEM OpenAPI** under **Content management**. **2. Enter the connection details on Basic** | Field | What to enter | | - | - | | **Integration name** | A name for this integration, for example `AEM Production`. Required. | | **AEM base URL** | The AEM author URL, for example `https://author-p12345-e67890.adobeaemcloud.com`. Required. It cannot be changed after the integration is created. | | **Authentication type** | **Server-to-server** (default) or **Authenticate as user**. It cannot be changed after the integration is created. | For **Server-to-server**: | Field | What to enter | | - | - | | **Client ID** | The OAuth Server-to-Server credential's Client ID. Required. | | **Client secret** | The OAuth Server-to-Server credential's Client Secret. Required. | | **Token URL** | Prefilled with the Adobe IMS token endpoint, `https://ims-na1.adobelogin.com/ims/token/v3`. Keep the default unless Adobe has instructed otherwise. | For **Authenticate as user**: | Field | What to enter | | - | - | | **OAuth web app client ID** | The OAuth Web App credential's Client ID (Adobe also calls it the API key). Required. | | **OAuth web app client secret** | The OAuth Web App credential's Client Secret. Required. | | **Token URL** | Read-only. The Adobe IMS OAuth web app token endpoint. | | **Redirect URI** | Read-only, with a copy button. Add this exact URI to the OAuth Web App credential in Adobe Developer Console. It differs between Gradial environments, so always copy it from the dialog. | **3. Set the optional Basic settings** | Field | What it does | | - | - | | **Legacy AEM read fallback (optional)** | Select a legacy AEM integration whose author URL matches this one. Gradial pairs it with this integration so that reads OpenAPI cannot serve fall back to it, and so legacy-only operations such as asset uploads can run through it. The list shows every legacy AEM integration in your organization; choose one for the same author environment. Not used for **Authenticate as user** integrations. Default: **No legacy fallback**. | | **Content fragments workflow** | **Launch** (default): "Use Adobe CF launches for edits". Gradial stages Content Fragment changes in an Adobe CF Launch before promotion. **Direct edit**: "Edit master directly". Gradial updates the master Content Fragment. Choose the option that matches your content-approval process. | | **Experience Cloud tenant** | Optional. Your Adobe Experience Cloud tenant slug, used to link Gradial's Content Fragment results to the Content Fragment editor. Enter only the lowercase slug after `#/@` in an Experience Cloud URL. For example, in `https://experience.adobe.com/?repo=author-p1234-e5678.adobeaemcloud.com#/@wknd/aem/cf/admin`, enter `wknd`. | Server-to-server integrations also have a **Cloud Manager logs (optional)** section with **IMS organization ID** and **Program ID** fields. Only Gradial staff can see and edit these fields; see [Cloud Manager log access](#cloud-manager-log-access). **4. Select Next** **Next** checks that the required fields are filled in, then saves the connection and opens **Mappings**. It does not test the credential against Adobe or AEM, so a wrong Client ID, Client secret, or allowlist entry is not caught here. If you change a Basic field afterward, select **Next** again before returning to **Mappings**. **Cancel** closes the dialog and discards the saved connection. **5. Add page mappings** On **Mappings**, under **Page mappings**, select **Add mapping** and enter: | Field | What to enter | | - | - | | **Site path** | Required. The existing site root Gradial may work in, for example `/content/mysite`. Must start with `/content/`. All pages under it are included. | | **DAM path** | Required. The existing DAM root Gradial may work in, for example `/content/dam/mysite`. Must start with `/content/dam`. All assets and Content Fragments under it are included. | | **Default template (optional)** | The page template to use for new pages, for example `/conf/mysite/settings/wcm/templates/page`. Must start with `/conf/` or `/apps/`. | Select **Save** to add the mapping. Add one mapping per site and DAM root pair. Gradial checks each path against AEM when you leave the field, and you cannot save a mapping until both paths pass. The DAM path is checked with Adobe's Folders API. The Site path is checked with Adobe's Pages API, which needs the **AEM CS Sites Content Management** API product on the credential, so include that product even if you mainly work with assets. If Gradial cannot reach AEM with the credential, for example before a user has connected their Adobe account or while the Client ID is not yet allowlisted, it checks the path format only and shows "Path format is valid, but AEM access was not remotely verified." The **Mappings** tab also shows **Default experience fragment template** and **Experience fragment paths**. AEM OpenAPI integrations do not perform Experience Fragment operations, so you can leave these empty. **6. Select Save** Select **Save** to create the integration. For **Authenticate as user**, Gradial then sends you to Adobe sign-in to connect your own account. ### What mappings control Mappings set the AEM paths Gradial may work in. Gradial checks every Content Fragment, folder, asset, and page operation against them: | Operation | Must be under | | - | - | | Content Fragments, Content Fragment Launches, DAM folders, and assets | A mapped **DAM path** | | Pages and sites | A mapped **Site path** | Without mappings, Gradial refuses Content Fragment, folder, asset, and page operations. The only exception is creating a Launch for Content Fragments under `/content/dam`, which Adobe validates instead. Add at least one mapping before using the integration. You can add, edit, or delete mappings later by editing the integration. ## Cloud Manager log access > [!NOTE] > > The **Cloud Manager logs (optional)** fields (**IMS organization ID** and **Program ID**) can be viewed and edited only by Gradial staff. They do not appear in the integration dialog for customer admins. To enable or change Cloud Manager log access, contact your Gradial representative. Cloud Manager log access is optional and available only for **Server-to-server** integrations. When it is configured, Gradial support engineers can read your AEM as a Cloud Service environment logs through Adobe's Cloud Manager API, using the same OAuth Server-to-Server credential as the integration. Gradial uses this access to diagnose problems that appear only in AEM or Dispatcher logs. What Gradial accesses and how: * **Read-only.** Gradial only lists environments and reads or downloads the logs that Cloud Manager makes available. It makes no changes in Cloud Manager. * **Which logs.** Gradial can access the logs Adobe offers for each environment, such as the author and publish `aemerror`, `aemrequest`, and `aemaccess` logs and the Dispatcher `httpderror`, `httpdaccess`, and `aemdispatcher` logs. Gradial limits reads to the last 7 days, which matches Adobe's retention period. * **Who and when.** A signed-in Gradial engineer reads logs on demand from an internal Gradial support tool. Gradial's AI agents do not read Cloud Manager logs, and no background job collects them. * **No storage.** Gradial streams log contents from Adobe for viewing or download and does not store them. * **Audit trail.** Gradial records an audit event for each access. The event names the Gradial user, the integration, and the environment, service, and log, but not the log contents. To enable it: 1. In the Adobe Developer Console project for this integration, add the **Cloud Manager** API to the OAuth Server-to-Server credential, and assign a product profile that can read environment logs. Adobe's [Cloud Manager API permissions](https://developer.adobe.com/experience-cloud/cloud-manager/guides/getting-started/permissions) allow the **Developer** and **Deployment Manager** roles to list logs; downloading log files requires **Deployment Manager**. 2. Find your **IMS organization ID**. It is shown on the credential details in Adobe Developer Console, in the form `1234567890ABCDEF@AdobeOrg`. 3. Find your **Program ID**. It is the number after `/program/` in the Cloud Manager URL, and the number after `author-p` in your author URL. For example, in `https://author-p12345-e67890.adobeaemcloud.com` the Program ID is `12345`. 4. Send both values to your Gradial representative. Only Gradial staff can enter the **IMS organization ID** and **Program ID** fields on the integration, and both must be set together. To turn off Cloud Manager log access, ask Gradial to clear these fields, or remove the Cloud Manager API or its product profile from the credential in Adobe Developer Console. ## Connect an individual AEM user This step applies only to **Authenticate as user** integrations. After an admin has saved the integration: 1. Each Gradial user opens **Settings -> Integrations**. 2. On the AEM OpenAPI integration, select **Connect AEM**. 3. Sign in through Adobe and approve the requested access. 4. Return to Gradial. A confirmation reads "AEM OpenAPI account connected", and the button shows **Connected to AEM**. Gradial stores each user's authorization separately, not as a shared integration token. The button shows **Reconnect AEM** with guidance when: * The stored authorization can no longer be used: "The stored AEM authorization can no longer be used. Reconnect to continue." * Adobe did not grant a permission Gradial needs, such as AEM Launches or the experimental AEM APIs. Gradial names the missing permission. Enable the matching AEM API in the Adobe Developer Console project, then reconnect. * Adobe did not report the granted permissions. Confirm the required AEM APIs are enabled in Adobe Developer Console, then reconnect. A user must connect, or reconnect, before Gradial can make OpenAPI calls on their behalf. The Adobe sign-in must be completed by the same Gradial user who started it. ## Manage an existing integration Open the integration and select **Edit** to change its name, mappings, **Content fragments workflow**, **Experience Cloud tenant**, or **Legacy AEM read fallback**. The connection details are read-only. To change the AEM base URL, authentication type, Client ID, or Client secret, create a new integration. ## Verify the setup Because **Next** and **Save** do not call Adobe with the credential, the first operation is the real test. Start with a safe read inside a mapped path, such as searching Content Fragments or assets. Then test the write workflow appropriate for your environment. ### Verification checklist 1. Confirm the integration saves and appears under **Settings -> Integrations**. 2. Confirm each mapping's Site path and DAM path validated against AEM, rather than showing "Path format is valid, but AEM access was not remotely verified." 3. Run a read within a mapped path, such as a Content Fragment or asset search. 4. In a non-production environment, run the smallest relevant write operation. 5. For **Authenticate as user**, verify the resulting AEM audit information shows the signed-in Adobe user rather than a technical account. ## Capability boundaries Through AEM OpenAPI alone, Gradial can: * Search, read, create, copy, and update Content Fragments, and search their variations. * Create and promote Content Fragment Launches. * Create DAM folders and search assets. * List, read, create, update, and delete pages through Adobe's page-management APIs, where available. Adobe still marks these APIs experimental, while its Folders, Assets, Content Fragments, and Launches APIs are stable. Other AEM work needs a legacy AEM integration for the same author environment, including: * **Page previews and screenshots.** AEM OpenAPI tokens cannot render author pages. Gradial renders previews with a legacy AEM integration in your organization whose author URL matches; this does not depend on the **Legacy AEM read fallback** setting. Without one, the preview shows "AEM preview not configured". * **Asset uploads.** Uploading a file to the DAM uses AEM's classic upload flow, so Gradial runs uploads through a legacy AEM integration for the same author environment. Importing an asset from a URL is not available in Gradial today. * **Other legacy operations**, such as asset downloads, metadata updates and renditions, tags, publishing, workflows, Experience Fragments, MSM and language copies, and versions. For **Authenticate as user** integrations, Gradial never falls back to a legacy integration's service credentials, because the change would not be attributed to the signed-in user. Do not configure a legacy integration as a workaround for missing OpenAPI permissions: correct the OAuth credential, `api.yaml` allowlist, product profile, or AEM path permissions instead. ## Troubleshooting > **The AEM OpenAPI card is not visible** > > AEM OpenAPI has not been enabled for the organization. Contact your Gradial representative. If the card is visible but disabled, you are not an organization admin. > **403 Forbidden: IMS Client ID not allowlisted** > > The credential's Client ID is not in `config/api.yaml`, or the config pipeline has not deployed it to this environment. Confirm that the pipeline deployed to the same environment as the AEM base URL and that the allowlisted Client ID belongs to the credential saved in Gradial. A Full Stack or Web Tier pipeline does not deploy the allowlist. > **403 Forbidden: The access token is missing required scopes** > > The Adobe Developer Console project is missing the API product the operation needs. Add the product to the project (see step 1), then retry. For **Authenticate as user**, reconnect after adding it. > **Other 403 Forbidden errors** > > The technical account or signed-in user lacks AEM permission for the target path, or, for creates, updates, and deletes, the Adobe product profile is read-only. Grant the needed permission. > **The required Adobe API product is not available** > > The Adobe organization may not be entitled to that API. Confirm the target IMS organization in Adobe Developer Console, then contact Adobe support or the organization's Adobe administrator to request access. > **AEM returns 404 for an OpenAPI operation** > > Verify that the corresponding Adobe API product is attached to the project and that the operation is available in the target AEM as a Cloud Service environment. Adobe's page-management APIs are experimental and may not be available everywhere. > **Authenticate as user does not connect** > > Recheck the Redirect URI in Adobe Developer Console. It must exactly match the URI shown in the Gradial dialog, including the protocol, hostname, and path. If Gradial reports "AEM OpenAPI token exchange failed", also recheck the OAuth web app client ID and secret. Then reconnect while signed in to the intended Gradial user account. > **A mapping path shows an error** > > "Site path not found in AEM" means the path does not exist or the credential cannot read it. Enter an existing root path and confirm the technical account or signed-in user can read it. "Path format is valid, but AEM access was not remotely verified" means Gradial could not call AEM with the credential; check the allowlist and, for **Authenticate as user**, connect your Adobe account. > **An operation fails because the path is not allowed** > > Add a mapping that covers the path: a DAM path for Content Fragments, folders, and assets, or a Site path for pages. Gradial refuses these operations outside mapped paths, and refuses them entirely when no mappings exist. > **A page preview shows AEM preview not configured** > > Add a legacy AEM integration with the same author URL. AEM OpenAPI tokens cannot render author pages. ## Adobe references * [Adobe Experience Manager API catalog](https://developer.adobe.com/experience-cloud/experience-manager-apis/) * [OpenAPI-based AEM APIs overview](https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/aem-apis/openapis/overview) * [Set up OpenAPI-based AEM APIs](https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/aem-apis/openapis/setup) * [Register a Client ID with `api.yaml`](https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/implementing/developing/open-api-based-apis) * [Use config pipelines](https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/operations/config-pipeline) * [Invoke OpenAPI-based AEM APIs with an OAuth Web App](https://experienceleague.adobe.com/en/docs/experience-manager-learn/cloud-service/aem-apis/openapis/invoke-api-using-oauth-web-app) ## Need help? Contact your Gradial representative or use the [Gradial support portal](https://portal.usepylon.com/gradial). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.