AEM OpenAPI

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.

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 or AMS / AEM as a Cloud Service 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.

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.

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, 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.

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:

kind: "API"
version: "1"
data:
  allowedClientIDs:
    author:
      - "<Adobe OAuth Client ID>"

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 (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.

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.”

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.

Open the dialog

In Gradial, go to Settings -> Integrations, select Connect integration, then select AEM OpenAPI under Content management.

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.

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.

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.

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.

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

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:

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 allow the Developer and Deployment Manager roles to list logs; downloading log files requires Deployment Manager.
Find your IMS organization ID. It is shown on the credential details in Adobe Developer Console, in the form 1234567890ABCDEF@AdobeOrg.
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.
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:

Each Gradial user opens Settings -> Integrations.
On the AEM OpenAPI integration, select Connect AEM.
Sign in through Adobe and approve the requested access.
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

Confirm the integration saves and appears under Settings -> Integrations.
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.”
Run a read within a mapped path, such as a Content Fragment or asset search.
In a non-production environment, run the smallest relevant write operation.
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

Need help?

Contact your Gradial representative or use the Gradial support portal.

Integrations

Ticketing Systems

Managing Access

Overview

Server-to-server

Authenticate as user

Before you start

Ensure AEM API access is enabled

Roles and coordination

Configure Adobe

1. Create an Adobe Developer Console project

2. Choose and create the credential

3. Grant the right Adobe and AEM permissions

4. Allowlist the Adobe Client ID in AEM

5. Plan environments deliberately

Adobe-side checklist

Add the integration in Gradial

What mappings control

Cloud Manager log access

Connect an individual AEM user

Manage an existing integration

Verify the setup

Verification checklist

Capability boundaries

Troubleshooting

Adobe references

Need help?

​Overview

Server-to-server

Authenticate as user

​Before you start

​Ensure AEM API access is enabled

​Roles and coordination

​Configure Adobe

​1. Create an Adobe Developer Console project

​2. Choose and create the credential

​3. Grant the right Adobe and AEM permissions

​4. Allowlist the Adobe Client ID in AEM

​5. Plan environments deliberately

​Adobe-side checklist

​Add the integration in Gradial

​What mappings control

​Cloud Manager log access

​Connect an individual AEM user

​Manage an existing integration

​Verify the setup

​Verification checklist

​Capability boundaries

​Troubleshooting

​Adobe references

​Need help?

Overview

Before you start

Ensure AEM API access is enabled

Roles and coordination

Configure Adobe

1. Create an Adobe Developer Console project

2. Choose and create the credential

3. Grant the right Adobe and AEM permissions

4. Allowlist the Adobe Client ID in AEM

5. Plan environments deliberately

Adobe-side checklist

Add the integration in Gradial

What mappings control

Cloud Manager log access

Connect an individual AEM user

Manage an existing integration

Verify the setup

Verification checklist

Capability boundaries

Troubleshooting

Adobe references

Need help?