Embed Athena Assets

Embed a native Athena asset in your application so users can view—and, where supported, edit—it without leaving your product. AthenaAssetEmbed accepts an asset ID and automatically renders the appropriate Athena viewer.

Supported asset types

Athena currently provides embedded viewers for:

• Spreadsheets
• Athena documents and Word documents
• User Interfaces
• PowerPoint presentations
• Images and PDFs
• Notebooks
• Figures
• Semantic models
• Video sessions

The controls available depend on the asset type. For example, a full spreadsheet embed includes the native toolbar, formula bar, sheet tabs, formatting controls, and collaboration experience, while a PDF embed provides its native document viewer.

Raw video, audio, text, web page, email, meeting, query snippet, dashboard, and AOP assets cannot currently be embedded. Some legacy native document and presentation formats must be exported to PDF before embedding.

Before you begin

You need:

• The ID of a supported Athena asset that the current user can view
• An Athena user access token for browser applications, or an Athena API key kept on your server
• A container with an explicit height for the embedded asset

To create an asset programmatically, see Create Assets.

Embed with React

The recommended integration for React applications is AthenaAssetEmbed from @athenaintel/react. The component generates a signed embed URL, renders the asset in an iframe, and synchronizes the current user’s authentication with the embedded Athena application.

Install the React SDK

$
npm install @athenaintel/react

Render the full asset experience

1
import {
2
  AthenaAssetEmbed,
3
  AthenaProvider,
4
} from '@athenaintel/react';
5
import '@athenaintel/react/styles.css';
6
7
interface AssetViewProps {
8
  accessToken: string;
9
  assetId: string;
10
}
11
12
export function AssetView({
13
  accessToken,
14
  assetId,
15
}: AssetViewProps) {
16
  return (
17
    <AthenaProvider config={{ token: accessToken }}>
18
      <div style={{ height: 800, width: '100%' }}>
19
        <AthenaAssetEmbed
20
          assetId={assetId}
21
          displayMode="full"
22
          readOnly={false}
23
          expiresInSeconds={60 * 60}
24
          title="Athena asset"
25
          onError={(error) => {
26
            console.error('Could not load the asset', error);
27
          }}
28
        />
29
      </div>
30
    </AthenaProvider>
31
  );
32
}

displayMode="full" renders the complete native experience available for that asset type. Use displayMode="minimal" for a lean viewing or editing surface.

readOnly={false} requests editing access; it does not grant it. If the current user can only view the asset, Athena automatically issues a read-only embed. Set readOnly to true when editing should never be available in the embedded experience.

Component options

The component also accepts standard iframe properties except src, onLoad, and onError.

Embed with an iframe

For a non-React application—or for an Athena User Interface asset—generate an embed URL on your server and use it as the iframe source.

Generate a signed embed URL

1
const response = await fetch(
2
  'https://api.athenaintel.com/api/embed/generate-token',
3
  {
4
    method: 'POST',
5
    headers: {
6
      'Content-Type': 'application/json',
7
      'X-API-KEY': process.env.ATHENA_API_KEY!,
8
    },
9
    body: JSON.stringify({
10
      asset_id: 'your-athena-asset-id',
11
      display_mode: 'full',
12
      read_only: false,
13
      expires_in_seconds: 60 * 60,
14
    }),
15
  },
16
);
17
18
if (!response.ok) {
19
  throw new Error(`Could not generate embed URL: ${response.status}`);
20
}
21
22
const { embed_url: embedUrl } = await response.json();

You can send Authorization: Bearer <user-access-token> instead of X-API-KEY when generating the URL on behalf of an authenticated Athena user.

The response includes:

1
{
2
  "token": "signed-embed-token",
3
  "embed_url": "https://app.athenaintel.com/embed/signed-embed-token",
4
  "expires_at": 1785772800,
5
  "asset_id": "your-athena-asset-id",
6
  "read_only": false,
7
  "display_mode": "full"
8
}

Render the URL

1
<iframe
2
  src="EMBED_URL_FROM_YOUR_SERVER"
3
  title="Athena asset"
4
  width="100%"
5
  height="800"
6
  style="border: 0"
7
  allow="fullscreen"
8
></iframe>

The same iframe markup can be placed in the index.html of an Athena User Interface asset.

Access and collaboration

• The user generating an embed must be allowed to view the asset.
• An editable embed is issued only when that user can also edit the asset. Athena downgrades all other requests to read-only.
• Read-only embeds omit editing controls for asset types that support editing.
• Editable collaborative assets connect to the same live content as Athena, so changes and collaborators stay synchronized.
• The requested display mode and access level are signed into the token and cannot be upgraded by changing iframe query parameters.

Troubleshooting

The asset is read-only

Confirm that readOnly is false and that the user generating the embed has edit permission for the asset. Requesting an editable embed cannot override the user’s Athena permissions.

The embed has no visible height

AthenaAssetEmbed fills its parent container. Give the parent an explicit height, such as height: 800px or a viewport-based height.

The embed token expired

Create a new embed URL. AthenaAssetEmbed handles URL generation for you when the component mounts; applications managing iframe URLs directly must renew them on the server.

Authentication fails in the browser

Use a valid Athena user access token with AthenaProvider. Do not substitute a server API key in client-side code.