Access control

Access control enables trusted per-user metadata to be injected into widget sessions, so that content filters can be enforced on a per-user basis. Your backend mints a signed token (JWT/HMAC) carrying user attributes (e.g. audience=admin ); the widget sends this token in the X-Api-Metadata header; the platform validates it against the HMAC signing key and enforces the content-filter rules scoped to that user.

Pre-requisites

You must have the site:manage:access_control permission to edit the metadata schema.
You must have the site:access_control:key_download permission to generate or rotate the signing key.

Choose Server-to-Server or Browser credential depending on your integration type. Note the client ID.

Add the IMS client identity to Guides Knowledge AI.

In Guides Knowledge AI, go to Security → Users and click Add user. Enter the email or service-account identifier associated with the IMS client and invite them to the organization.

Create or select a domain-scoped role that includes the required permissions.

Go to Security → Roles and create (or select) a domain-scoped role that includes the Download Signing Key and Manage Access Control permissions.

Assign that role to the user added in the previous step for the relevant domain(s).

Configure the allowed metadata vocabulary.

Navigate to Settings → Access control on the target domain.

In the Allowed metadata table, add rows defining the permitted vocabulary: each row is an Attribute (e.g. audience) and a Value (e.g. admin or internal).

If the table is empty, any well-signed claim is accepted.

Check Enable metadata based access check to enforce content filters based on the token's metadata. When enabled, users whose tokens do not carry matching attributes will not see content restricted by content-filter rules.

Generate the HMAC signing key.

In the Signing key section, click Generate key. The HMAC secret is shown only once — copy it immediately and store it securely.

To rotate the key, click Rotate key. Existing tokens signed with the old key will stop working immediately.

Your backend signs a JSON payload of user attributes with this secret and passes the result as the X-Api-Metadata header in widget API calls. The platform verifies the signature before applying metadata-based content filtering.

Keep the signing secret in a secrets manager (e.g. AWS Secrets Manager, Azure Key Vault). Never hard-code it in client-side JavaScript. Rotate the key immediately if you suspect it has been compromised.

FAQ

What is access control and how does it work with widget sessions?

Access control lets you inject trusted per-user metadata into widget sessions so content filters can be enforced per user. Your backend mints a signed token (JWT/HMAC) with user attributes (for example, audience=admin), and the widget sends it in the X-Api-Metadata header. The platform validates the token against the HMAC signing key and applies content-filter rules scoped to that user.

What permissions do I need to configure access control?

To edit the metadata schema, you need the site:manage:access_control permission. To generate or rotate the signing key, you need the site:access_control:key_download permission. These permissions are typically included in a domain-scoped role you assign to the relevant user.

How do I set up an IMS OAuth client and add it to Guides Knowledge AI for access control?

First, register a new IMS OAuth client at developer.adobe.com and choose Server-to-Server or Browser credentials based on your integration type, then note the client ID. Next, in Guides Knowledge AI go to Security → Users, click Add user, and invite the email or service-account identifier associated with the IMS client to the organization. Then create or select a domain-scoped role with Download Signing Key and Manage Access Control permissions and assign it to that user for the relevant domain(s).

How do I configure the allowed metadata vocabulary and enable metadata-based access checks?

Go to Settings → Access control on the target domain and use the Allowed metadata table to define permitted Attribute/Value pairs (for example, attribute audience with value admin or internal). If the table is empty, any well-signed claim is accepted. Enable “Enable metadata based access check” to enforce content filters based on token metadata; users whose tokens don’t match required attributes won’t see content restricted by content-filter rules.

How do I generate or rotate the HMAC signing key, and what happens to existing tokens?

In the Signing key section, click Generate key; the HMAC secret is shown only once, so you must copy it immediately and store it securely. To rotate the key, click Rotate key—tokens signed with the old key stop working immediately. Your backend signs a JSON payload of user attributes with this secret and sends it as the X-Api-Metadata header, which the platform verifies before applying metadata-based content filtering.