Embed Integration Guide

This guide covers the complete API flow for dashboard and visualization embeds.

Overview

The integration has 3 steps:

1. Exchange api_key + api_secret for JWT tokens.
2. Generate an embed token for a dashboard or visualization.
3. Use the returned embed_url in an iframe (or call public info/execute endpoints).

Prerequisites

• An integration user with an active API key.
• Your company_slug.
• A target resource_id (dashboard or visualization).
• Permission to access the resource.

Base URL by Environment

Environment	Base URL
Local	http://localhost:3100
Production	https://api.console.solucao42.com.br

Define a variable to reuse in examples:

export API_BASE_URL="http://localhost:3100"

The embed_url domain returned by the API follows FRONTEND_URL configured in console-api.

Step 1: Authenticate with API Key

Use API key credentials only to obtain JWT tokens. Do not send API keys in regular API calls.

curl -X POST "$API_BASE_URL/api/v1/auth/api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "company_slug": "acme",
    "api_key": "s42_xxxxxxxxx",
    "api_secret": "xxxxxxxxx"
  }'

Expected response:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "access_token_expires_in": 600,
  "refresh_token_expires_in": 604800,
  "user": {
    "_id": "...",
    "email": "integration@acme.com"
  }
}

Step 2A: Generate Dashboard Embed

curl -X POST "$API_BASE_URL/api/v1/embed/dashboards/DASHBOARD_ID" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "fixed_params": { "region": "south" },
    "allowed_params": ["seller_id"],
    "required_params": ["region"],
    "expires_in": 3600
  }'

Step 2B: Generate Visualization Embed

curl -X POST "$API_BASE_URL/api/v1/embed/visualizations/VISUALIZATION_ID" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "allowed_params": ["start_date", "end_date"],
    "required_params": ["start_date", "end_date"],
    "expires_in": 1800
  }'

Generation response (dashboard and visualization):

{
  "embed_url": "<FRONTEND_URL>/embed/d/eyJ...",
  "token": "eyJ...",
  "expires_at": "2026-03-05T15:00:00.000Z"
}

Parameter Controls

Field	Type	Description
fixed_params	object	Parameters locked in the token. Cannot be overridden by query string.
allowed_params	string[]	Parameters that are allowed via embed URL query string.
required_params	string[]	Required parameters. Must exist in fixed_params or query string.
expires_in	integer	Token expiration in seconds. Min: 60, max: 86400.

Step 3: Render in an iframe

Use only the returned embed_url:

EMBED_URL=$(curl -s -X POST "$API_BASE_URL/api/v1/embed/dashboards/DASHBOARD_ID" ... | jq -r '.embed_url')
echo "$EMBED_URL"

Do not copy the full JSON response into the URL. Copy only the embed_url value.

Iframe example:

<iframe
  src="<embed_url>"
  width="100%"
  height="600"
  frameborder="0"
  loading="lazy"
></iframe>

Public Embed Endpoints

After token generation, public stateless consumption is available through:

Method	Endpoint	Purpose
GET	/api/embed/d/:token/info	Dashboard metadata and parameter policy
GET	/api/embed/d/:token/filters/:filter_slug/options	Resolve select and multi_select filter options
POST	/api/embed/d/:token/execute	Execute dashboard visualizations
GET	/api/embed/v/:token/info	Visualization metadata
POST	/api/embed/v/:token/execute	Execute visualization

You can pass allowed parameters via query string (example: ?seller_id=42).

For dynamic filters, you can pass search:

curl "$API_BASE_URL/api/embed/d/EMBED_TOKEN/filters/status/options?search=act"

Response:

{
  "filter_slug": "status",
  "options": [
    { "label": "Active", "value": "Active" }
  ],
  "source": "dynamic"
}

source can be static, dynamic, or policy.

Common Errors

HTTP	error_code	Typical cause
400	INVALID_ID	Invalid resource ID
400	PARAMETER_VALIDATION_ERROR	Missing or disallowed parameters
401	TOKEN_INVALID	Invalid embed token
401	TOKEN_EXPIRED	Expired embed token
404	DASHBOARD_NOT_FOUND	Dashboard not found
404	VISUALIZATION_NOT_FOUND	Visualization not found

Security Best Practices

• Never expose api_key and api_secret in frontend code.
• Generate embed URLs from your backend only.
• Use short expires_in values for sensitive links.
• Prefer fixed_params to enforce data scope.
• Refresh JWT tokens with POST /api/v1/auth/refresh when needed.