Skip to main content

Security and Data Handling Guide

This guide summarizes the customer-facing security and data handling expectations for ACP Engine integrations. It is intentionally high-level and focuses on operational responsibilities, safe integration patterns, and data boundaries.

Authentication Model​

ACP Engine uses credential-based token exchange:

  1. The customer integration receives an access_key and secret_key.
  2. The integration exchanges those credentials for a short-lived bearer token.
  3. API requests use the bearer token in the Authorization header.

Secret keys should be handled as sensitive credentials and stored only in approved secure systems.

Credential Handling​

Customer teams should:

  • Store secret keys in a secure secrets manager or backend environment.
  • Avoid storing secret keys in browser code, mobile bundles, repositories, logs, tickets, or screenshots.
  • Use separate credentials for development, UAT, and production.
  • Rotate credentials on a regular schedule.
  • Rotate credentials immediately when access ownership changes.

Customer teams should not:

  • Send secret keys to frontend clients.
  • Embed secret keys in JavaScript bundles.
  • Share credentials in email or chat tools.
  • Use production credentials in test environments.

Token Handling​

Bearer tokens are short-lived and should be treated as sensitive.

Recommended practices:

  • Keep tokens only as long as needed.
  • Re-run token exchange when a token expires.
  • Use secure transport for every API request.
  • Do not log full token values.
  • Do not expose token values in customer-visible UI.

Runtime session resume_token values are separate signed authorization artifacts. ACP binds them to the realm, session, privacy-safe subject hash, token version, and expiry. Keep them only in protected BFF/server or HttpOnly state, send them whenever a newly created session is resumed, and never place them in browser-readable storage, analytics, URLs, or logs. A session_id alone is not resume authorization. Refresh rotates the token and invalidates its predecessor. Recovery without the previous token requires a dedicated runtime:session_recover service capability. See Runtime Sessions, Chat IDs, and Recovery.

Data Boundaries​

ACP Engine receives data needed to process runtime requests, route tools, execute flows, and generate responses. Customer teams should only send the data required for the current interaction.

Avoid sending:

  • Payment card numbers.
  • Private access tokens.
  • Raw passwords.
  • Unnecessary personal data.
  • Internal-only customer secrets.
  • Large documents that are not needed for the specific runtime task.

MCP Data Handling​

Customer MCP servers should return only the data required for the requested tool result.

Recommended MCP response practices:

  • Return structured JSON.
  • Keep error messages safe and customer-appropriate.
  • Avoid returning secrets or backend credentials.
  • Use stable IDs instead of exposing implementation details.
  • Apply customer-side authorization before returning protected business data.
  • Mask or omit sensitive fields when they are not needed by the AI or frontend.

Public ACP MCP Credentials​

The unified ACP MCP service uses a merchant API key through Authorization: Bearer or x-api-key for Catalog tools. Realm-bound Engine tools use X-ACP-Realm-ID, X-ACP-Access-Key, and X-ACP-Secret-Key. Keep all of these values in the MCP host's secret storage. Do not place them in browser code, prompts, tool arguments that may be logged, or shared MCP configuration files committed to source control.

When MCP_SHARED_SECRET is configured, X-MCP-API-Key or X-ACP-API-Key adds transport-level protection at the public MCP endpoint. It does not replace merchant-key or realm-identity validation.

Downstream Merchant MCP Credentials​

  • Treat a Merchant Services tr_live_... key as a server-side secret and use the narrowest store/custom scope that supports the ACP flow.
  • Prefer a finite expiration and rotate the registration before the key expires.
  • Expired and revoked keys cannot authenticate. Revocation is permanent, and Merchant Services requires revocation before hard deletion.
  • When rotating a downstream key, update the ACP MCP server registration, run the connection test, refresh tool discovery, and only then revoke the previous key.
  • Do not copy Merchant Services keys into browser configuration, runtime messages, tool arguments, logs, or support exports.
  • Remember that approved write tools may change catalog/procurement data and trigger merchant-configured outbound webhooks.

Catalog and Enrichment Data​

  • Use stable SKU or external IDs for idempotent product synchronization.
  • Send payment-provider references only. Do not send raw card numbers or card verification values to Catalog.
  • Treat customer, shipping, billing, product metadata, and generated enrichment content according to the customer's approved data-retention policy.
  • Confirm that an Enrichment provider is approved for both the content type and deployment region before enabling a job.
  • Keep realm runtime providers and merchant Enrichment providers in their separate registries.
  • Review store Enrichment usage separately from realm runtime AI usage.

Manager CLI​

The embedded Manager CLI is an authenticated, read-only inspection surface with an allowlisted command set. It is not a Linux shell and does not accept arbitrary SQL. CLI output can still contain operational identifiers; apply the same screenshot, support-export, and access-control rules used for Manager pages. Merchant/store Catalog and Enrichment data is accessed through its dedicated dashboards and API surfaces.

Frontend Data Handling​

Frontend applications should:

  • Send user intent and required context to ACP Engine.
  • Preserve session_id and its protected resume_token for continuity.
  • Avoid sending unnecessary sensitive data.
  • Render structured data safely.
  • Capture trace IDs for support without exposing private payloads to users.

Frontend applications should not:

  • Reimplement assistant behavior or MCP tool-selection logic.
  • Call MCP servers directly unless an approved integration exception exists.
  • Store service credentials client-side.

Logging and Support​

When reporting an issue, include:

  • Environment name.
  • Timestamp.
  • trace_id, if available.
  • session_id, if relevant.
  • Endpoint name.
  • High-level scenario description.

Do not include:

  • Secret keys.
  • Full bearer tokens.
  • Private customer data unrelated to the issue.
  • Raw payment data.
  • Credentials for downstream systems.

Access Control Expectations​

Use the least access needed for each integration:

  • Admin users manage realm configuration.
  • Merchant roles and Merchant Access govern merchant teams, developer keys, and stores independently from realm membership.
  • Merchant API keys use the narrowest merchant, store, or custom scope required by the integration.
  • Service identities are used for backend-to-backend integrations.
  • Agent identities are used for runtime assistant behavior.
  • MCP server access should be limited to the tools and data required by the customer flow.

Environment Separation​

Use separate resources for each environment:

  • Development
  • QA
  • UAT
  • Production

Each environment should have separate credentials, realm configuration, MCP server endpoints, provider settings, and operational ownership.

Customer Security Review Checklist​

  • Credentials are stored in an approved secret store.
  • No secret keys are present in frontend code.
  • Production and test credentials are separated.
  • MCP servers use HTTPS in production.
  • MCP tools return only required data.
  • Logs do not contain full tokens or secret values.
  • Raw external session subjects are not stored; session ownership uses a realm-scoped subject hash.
  • Flow classification uses only the realm default active text provider and respects the execution's data-egress policy.
  • User context does not contain unnecessary sensitive data.
  • Support process includes trace IDs but excludes secrets.
  • Credential rotation process is defined.