---
title: "Issue a temporary Dashboard embed URL"
method: POST
path: "/api/v3/dashboards/{dashboard_id}/embed-session/"
tags: ["Dashboards"]
---

# Issue a temporary Dashboard embed URL

`POST /api/v3/dashboards/{dashboard_id}/embed-session/`

## Request

- Base URL: `https://embedded.improvado.io`
- URL: `https://embedded.improvado.io/api/v3/dashboards/{dashboard_id}/embed-session/`
- Auth: HTTP basic
- TypeScript: <https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/docs/api/v3/dashboards/:dashboard_id/embed-session/post.ts> (a function with typed inputs; its response is checked against the schema)

Create a read-only URL for one React Dashboard in the selected workspace.
The API user must have access to both the workspace and the dashboard. Access is
checked again when issuing a URL, even if the dashboard was previously listed.
This does not create or enable a permanent public sharing link.

**Call from your backend only.** Authenticate and authorize the viewer in your
application before requesting a URL. Give the browser only the returned `url`,
which can be used as an iframe `src` on an external HTTPS site.

The URL contains a bearer credential that anyone possessing it can reuse for
**15 minutes from issuance**. It is not bound to a named viewer and is not the
one-time authorization code used by data-source iframes. It allows viewing the
selected dashboard, without editing, agent chat or general workspace access.
Treat the complete URL as a secret; do not log it or share it with unauthorized users.

After expiry, reauthorize your viewer, request a new URL and replace/reload the
iframe. Reusing a URL does not extend its lifetime. Already displayed data cannot
be retracted. Dashboard-specific permission changes may take up to 15 minutes
to affect previously issued access. No customer-facing revocation endpoint or
automatic iframe refresh is provided by this API.

The URL uses the configured regional embedded host, such as
`embedded.improvado.io`, `embedded.eu.improvado.io` or `embedded.us.improvado.io`.

## Path parameters

- `dashboard_id` integer, required

## Request body

- DashboardEmbedSessionRequest
  - `workspace_id` integer, required: Workspace accessible to the API user and containing the selected dashboard.

## Response `201`

Temporary read-only embed URL and its absolute expiry.

- DashboardEmbedSessionResponse
  - `url` string, uri, required: Secret, reusable bearer URL for iframe viewing; expires 15 minutes after issuance.
  - `expires_at` string, date-time, required: Absolute UTC expiry. Request a new URL and reload the iframe after this time.

## Other responses

- `400`: Missing or invalid workspace_id, or a non-integer dashboard_id. Validation errors contain a detail array; request parsing errors contain a detail string.
- `401`: Valid Embedded API Basic credentials are required; cookie-only and Bearer authentication are not accepted.
- `403`: Dashboard or workspace not found, unsupported dashboard type, insufficient permissions, or Embedded API access is not enabled.
- `503`: Dashboard authorization is temporarily unavailable. No URL is issued.

---

[API](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3.md) - [All operations](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/llms.txt) - [OpenAPI document](https://skmtc.dev/improvado/apis/improvado-embedded-api-v3/revisions/a881099bd6c4?raw)