Skip to main content

Send and receive messages

This reference provides message types, payload shapes, and usage patterns for communication between your embedded app and the product via postMessage. Use this document to look up which messages the product sends (handshake, auth context, logout) and which messages your app sends (ready signal, token request, error).

Messages from Atlan to your app​

ATLAN_HANDSHAKEmessage
Required

Sent immediately after the iframe loads.

{
  type: 'ATLAN_HANDSHAKE',
  payload: {
    appId: string
  }
}

ATLAN_AUTH_CONTEXTmessage
Required

Sent after your app responds with IFRAME_READY, on token refresh, and in response to IFRAME_TOKEN_REQUEST.

{
  type: 'ATLAN_AUTH_CONTEXT',
  payload: {
    token: string,
    expiresAt: number,
    user: {
      id: string,
      username: string,
      email: string,
      name: string
    },
    page: {
      route: string,
      params: Record<string, string | string[]>,
      query: Record<string, string | string[]>
    },
    timestamp: number
  }
}

For a complete payload, see Auth payload.

ATLAN_LOGOUTmessage
Required

Sent when the user logs out or the session ends.

{
  type: 'ATLAN_LOGOUT'
}

Messages from your app to Atlan​

IFRAME_READYmessage
Required

Required. Send this after your app initializes and is ready to receive auth context.

{
  type: 'IFRAME_READY'
}

IFRAME_TOKEN_REQUESTmessage
Optional

Request a fresh token.

{
  type: 'IFRAME_TOKEN_REQUEST'
}

IFRAME_ERRORmessage
Optional

Report an error that Atlan can display to the user.

{
  type: 'IFRAME_ERROR',
  payload: {
    message: string
  }
}

Minimal message handling example​

const ATLAN_ORIGIN = 'https://your-tenant.atlan.com'

window.addEventListener('message', (event) => {
  if (event.origin !== ATLAN_ORIGIN) return

  const { type, payload } = event.data || {}

  switch (type) {
    case 'ATLAN_HANDSHAKE':
      // Never use '*' as targetOrigin.
      window.parent.postMessage({ type: 'IFRAME_READY' }, ATLAN_ORIGIN)
      break
    case 'ATLAN_AUTH_CONTEXT':
      console.log('Authenticated user:', payload.user.username)
      break
    case 'ATLAN_LOGOUT':
      // Clear any cached session state
      break
  }
})

See also​