# Embedding files and diagrams

Show a read-only Eraser file or diagram in your own product, internal portal or docs site. Viewers don't need an Eraser account. For Notion or Confluence, use the [Notion](/using-the-notion-integration) or [Confluence](/using-the-confluence-integration) integration instead.

## How it works

1. Your server calls [Create an embed token](/reference/create-embed-token) with a team [API token](/reference/api-token) and the file or diagram to show.
2. Eraser returns an `embedUrl`.
3. Your page puts `embedUrl` in an iframe.

```bash
curl --location 'https://app.eraser.io/api/embedTokens' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer $YOUR-TOKEN-HERE' \
--data '{
    "fileId": "abc123",
    "content": [{ "type": "diagram", "id": "def456" }],
    "expiresIn": "1h"
}'
```

```html
<iframe src="EMBED_URL" width="100%" height="600" style="border: 0" title="Architecture diagram"></iframe>
```

Call the endpoint from your backend – the request carries your API token. Creating a new URL on every page view is fine; the limit is 20,000 requests an hour per token.

## Choose what to show

- **A file** – send only `fileId`. The embed shows the file's canvas, not its document.
- **A diagram** – add `{ "type": "diagram", "id": "<diagramId>" }` to `content`, with `fileId` set to the file that holds it.
- **A figure** – the same, with `"type": "figure"`. The embed shows the figure and everything inside it.

`content` takes up to 20 items. Several items are shown together, where they sit in the file. The embed fits its content to the iframe and refits when the iframe is resized.

### Finding IDs

- **File** – the part of the file's URL after `/workspace/`, or the `id` from [List files](/reference/list-files).
- **Diagram** – select it and choose **Copy link**. The ID is the `diagram` value in the link (`/workspace/<fileId>?diagram=<diagramId>`). [List diagrams in a file](/reference/list-diagrams) returns the same IDs.
- **Figure** – select it and choose **Copy link**. The ID is the `figure` value in the link (`/workspace/<fileId>?figure=<figureId>`).

An ID that isn't in the file fails with a `400`.

## Appearance

- **`theme`** – `light` (default) or `dark`, whatever the viewer's own setting.
- **`footer`** – the Eraser logo and the file title. `auto` (default) shows it on file embeds only; `always` and `never` override that. When it's hidden, the file title isn't sent to the viewer.
- **`titleLink`** – links the footer title to the file in Eraser. Defaults to `true`; turn it off for viewers outside your team.

Viewers can pan and zoom, but can't edit, comment, copy or export.

## Expiry

`expiresIn` takes a duration such as `"15m"`, `"12h"` or `"2w"` (units `s`, `m`, `h`, `d`, `w`), or a Unix timestamp in milliseconds. It defaults to `"1d"`, and the response's `expiresAt` gives the exact time. Anyone with the URL can view the embed until then, so keep expiries short.

Each load reads the file as it is then. An open embed doesn't update live.

## Revoking

Eraser doesn't store embeds, so there's nothing to delete one by one. Delete the API token that created an embed in [Settings → API Token](https://app.eraser.io/dashboard/all?settings=api-tokens), and every embed it created stops working. Use a separate token for each integration so you can revoke one without the others.

An embed also stops working if its file is made private, archived, deleted, moved to another team, or turned into a template or reference. If a selected diagram or figure is deleted, the embed shows a notice in its place rather than more of the file. Expired and revoked embeds show "This embed is unavailable."

## Requirements

- A team API token, which needs a paid plan. Organization-level tokens can't create embeds.
- On private cloud, use your own Eraser host instead of `app.eraser.io`.