Embed

Embed API

DbFace provides a JWT-based embed mechanism for placing a report or dashboard inside a third-party page. The focus is controlled access rather than anonymous public sharing.

Embed flow

An admin or editor enables embedding for a report.
A client generates an embed token through the API.
The returned embed_url or /embed/:id?token=... is used in the host page.
The server validates the token, expiration, report identity, and allowed domains.

Generate a token

POST /api/v1/embed/token/:report_id

{
  "expires_in": 86400,
  "allowed_domains": ["example.com", "*.mycompany.com"]
}

The response includes:

token
embed_url
expires_at
report_id and report_name

Token lifetime is constrained server-side. In practice it is limited to a range between 5 minutes and 30 days.

Embed settings

PUT /api/v1/embed/settings/:report_id

{
  "enabled": true,
  "allow_domains": ["example.com"]
}

This updates report-level embedding settings. The common configuration points are whether embedding is enabled and which domains are allowed.

Verify a token

POST /api/v1/embed/verify

{
  "token": "eyJ..."
}

Verification checks token validity, expiration, token type, and optionally whether the current request Origin matches the allowed domain rules.

Embed URL

The standard embed URL shape is:

/embed/:report_id?token=eyJ...

The frontend Embed page reads the token from the query string and forwards additional params as execution parameters for the report.

Permission constraints

Only admins and editors can generate embed tokens.
Tokens can only be generated for reports in the current organization.
Tokens are signed with the application secret key.

Best practices

Use different token expiration windows for different external systems.
Always configure allowed_domains instead of leaving origin access too broad.
Make sure the report is already published and fully validated before embedding it.