Skip to main content

Embedded app connection and authentication issues

Use this guide when your embedded app shows "Failed to respond," doesn't load in the iframe, or returns 401 or token errors. Follow the solutions below to fix handshake, CSP, and token handling issues.

App shows timeout or "failed to respond"​

Error

Failed to respond

Cause​

Your app doesn't complete initialization in time. This can happen if the app doesn't send the ready signal, or if startup code throws an error.

Solution​

  1. Open the browser developer tools and check for errors in the Console.
  2. Initialize authentication as early as possible in your app startup code.
  3. If you implemented postMessage manually, send IFRAME_READY immediately after receiving ATLAN_HANDSHAKE.
  4. Confirm allowed_origins includes your app origin (for example, https://app.company.com).

Asset GUID is missing in profile tab​

Error

Asset GUID is missing in profile tab

Cause​

Atlan only sends an asset GUID when your app renders in the asset-profile-tab slot and the slot conditions match the current asset.

Solution​

  1. Confirm the app is configured to render in the asset-profile-tab slot.
  2. If the app uses conditional rendering, confirm when.assetTypes includes the asset type you are testing.
  3. In your app, read the GUID from context.page.params.id.

App can't be embedded in iframe​

Error

Refused to display in a frame

Cause​

Your app blocks iframe embedding through response headers, such as CSP frame-ancestors or X-Frame-Options.

Solution​

  1. Add a CSP header that includes Atlan as a frame-ancestors origin:

    Content-Security-Policy: frame-ancestors 'self' https://*.atlan.com;

  2. Remove or change X-Frame-Options if it blocks embedding. Values like DENY and SAMEORIGIN prevent Atlan from loading your app in an iframe.

  3. Verify the header on your deployed URL:

    curl -I https://app.company.com | grep -i content-security-policy

App doesn't receive messages from Atlan​

Cause​

Your app ignores messages because the origin doesn't match, or messages are posted to the wrong target origin.

Solution​

  1. Confirm your app validates the parent origin (your Atlan tenant), for example https://your-tenant.atlan.com.
  2. Confirm you never use '*' as the targetOrigin when calling postMessage.
  3. Confirm allowed_origins in your app registration matches your app's deployed origin.

API calls fail with 401 or token errors​

Cause​

Your app uses an expired token, doesn't refresh tokens, or keeps tokens after session end.

Solution​

  1. Use the Atlan Auth SDK so token refresh and session changes are handled automatically.
  2. If you implement postMessage manually, request a fresh token before expiry using IFRAME_TOKEN_REQUEST.
  3. Clear cached tokens and session state when your app receives ATLAN_LOGOUT.

See also​

Need help​

If you need assistance after trying the steps, contact Atlan support: Submit a request.