Sharing Integration Guide

This guide covers the 3 sharing flows available in the API:

Public link (no external authentication).
Email sharing (one-time code authentication).
Embed (stateless token for iframe).

Endpoint Overview

Flow	Main endpoints
Public link	`GET /api/v1/public/shares/:token/resolve`, `POST /api/v1/public/shares/:token/execute`
Email (share portal)	`POST /api/v1/share-auth/request`, `POST /api/v1/share-auth/verify`, `GET /api/v1/share-portal/...`
Embed	`POST /api/v1/embed/dashboards/:id`, `GET/POST /api/embed/d/:token/...`
Dynamic filter options	`GET .../filters/:filter_slug/options` (public, portal, and embed)

Flow 1: Public Link

Use this when anyone with the link can access it.

1) Create a share without `share_context_id`

curl -X POST "$API_BASE_URL/api/v1/dashboards/DASHBOARD_ID/shares" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Public link - sales",
    "share_type": "link"
  }'

2) Resolve token

curl "$API_BASE_URL/api/v1/public/shares/SHARE_TOKEN/resolve"

3) Execute shared dashboard

curl -X POST "$API_BASE_URL/api/v1/public/shares/SHARE_TOKEN/execute" \
  -H "Content-Type: application/json" \
  -d '{
    "parameters": {
      "period_start": "2025-01-01",
      "period_end": "2025-12-31"
    }
  }'

Use this when only approved emails can access the dashboard.

curl -X POST "$API_BASE_URL/api/v1/share-contexts" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "External customers",
    "description": "External customer access"
  }'

2) Add an external email member

curl -X POST "$API_BASE_URL/api/v1/share-contexts/CONTEXT_ID/members" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "member_type": "external_email",
    "email": "customer@company.com"
  }'

curl -X POST "$API_BASE_URL/api/v1/dashboards/DASHBOARD_ID/shares" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Customer portal",
    "share_type": "link",
    "share_context_id": "CONTEXT_ID",
    "share_filter_policies": [
      {
        "filter_slug": "status",
        "filter_kind": "multi_select",
        "mode": "selectable",
        "allowed_values": ["Active", "Pending"]
      }
    ]
  }'

4) External user authenticates with code

Request code:

curl -X POST "$API_BASE_URL/api/v1/share-auth/request" \
  -H "Content-Type: application/json" \
  -d '{
    "company_slug": "acme",
    "email": "customer@company.com"
  }'

Verify code and get tokens:

curl -X POST "$API_BASE_URL/api/v1/share-auth/verify" \
  -H "Content-Type: application/json" \
  -d '{
    "company_slug": "acme",
    "email": "customer@company.com",
    "code": "1234-5678"
  }'

5) Use share portal with `share_access`

List dashboards for company/contexts:

curl "$API_BASE_URL/api/v1/share-portal/acme/dashboards" \
  -H "Authorization: Bearer SHARE_ACCESS_TOKEN"

Execute dashboard:

curl -X POST "$API_BASE_URL/api/v1/share-portal/acme/dashboards/DASHBOARD_SLUG/execute" \
  -H "Authorization: Bearer SHARE_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "context_id": "CONTEXT_ID",
    "parameters": {
      "status": ["Active"]
    }
  }'

Flow 3: Embed

Use this when the dashboard will be rendered in an iframe.

1) Generate token/embed URL

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

2) Consume public embed endpoints

GET /api/embed/d/:token/info
POST /api/embed/d/:token/execute
GET /api/embed/d/:token/filters/:filter_slug/options

Dynamic Filters (`select` / `multi_select`)

When a filter is dynamic (SQL-backed), the frontend must call the options endpoint for the current mode:

Public link: GET /api/v1/public/shares/:token/filters/:filter_slug/options
Email portal: GET /api/v1/share-portal/.../filters/:filter_slug/options?context_id=...
Embed: GET /api/embed/d/:token/filters/:filter_slug/options

Supported optional query parameter:

search: value used by the dynamic filter SQL.

Standard response:

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

source can be:

static: static filter options.
dynamic: options loaded from filter SQL.
policy: options restricted by share_filter_policies.

Common Errors

HTTP	`error_code`	Typical cause
`401`	`AUTH_REQUIRED`	Share requires external authentication
`401`	`TOKEN_INVALID`	Invalid/expired token
`400`	`INVALID_CONTEXT_ID`	Invalid `context_id` in portal mode
`403`	`FILTER_DISABLED_BY_POLICY`	Filter blocked by share policy
`400`	`DB_QUERY_ERROR`	Dynamic filter SQL execution failed
`400`	`SHARE_FILTER_POLICY_VIOLATION`	Parameters violate share rules

Endpoint Overview​

Flow 1: Public Link​

1) Create a share without share_context_id​

2) Resolve token​

3) Execute shared dashboard​

Flow 2: Email Sharing​

1) Create a share context​

2) Add an external email member​

3) Create a share bound to this context​

4) External user authenticates with code​

5) Use share portal with share_access​

Flow 3: Embed​

1) Generate token/embed URL​

2) Consume public embed endpoints​

Dynamic Filters (select / multi_select)​

Common Errors​

Next Steps​