# Embedded Configuration Mutations

Use this reference when the user wants to create, update, or delete embedded dashboard configuration.

Do not run these without explicit confirmation:

| Surface | Endpoint |
|---|---|
| Set embedded config | `POST /api/v1/dashboard/{id_or_slug}/embedded` |
| Update embedded config | `PUT /api/v1/dashboard/{id_or_slug}/embedded` |
| Delete embedded config | `DELETE /api/v1/dashboard/{id_or_slug}/embedded` |

Before mutating embedded configuration, summarize:

1. Workspace hostname.
2. Dashboard ID or slug.
3. Endpoint and HTTP method.
4. Allowed domains and expected origin behavior.
5. Expected embed UUID/configuration change.
6. Rollback path, such as restoring prior allowed domains or deleting the config.

Changing embedded configuration can expose dashboards to external applications when paired with valid guest tokens. For token issuance, use `preset-guest-tokens`. For RLS clauses, use `preset-embedded-rls`.

# Embedded Configuration Reads

Use this reference for embedded dashboard configuration reads.

Embedding endpoints depend on workspace feature flags and permissions. If embedding is disabled, embedded endpoints can return `404`.

## Dashboard Embedded Configuration

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/dashboard/{id_or_slug}/embedded" | jq .
```

```python
embedded = client.workspace(
    "GET",
    hostname,
    f"/dashboard/{dashboard_id_or_slug}/embedded",
)
```

`404` can mean no embedded configuration exists for the dashboard, the feature flag is disabled, or the authenticated user lacks access.

## Embedded Dashboard By UUID

```bash
curl -s -H "Authorization: Bearer $TOKEN" \
  "https://{workspace_hostname}/api/v1/embedded_dashboard/{uuid}" | jq .
```

```python
embedded = client.workspace("GET", hostname, f"/embedded_dashboard/{embedded_uuid}")
```

Optional query parameters include `uiConfig`, `show_filters`, `expand_filters`, `native_filters_key`, and `permalink_key`.

For allowed-domain interpretation, load [trusted-domains-and-origins.md](trusted-domains-and-origins.md).

# Embedded RLS Routing

Use this reference when an embedding task involves row-level security for external viewers.

Embedded RLS clauses are permission controls. Incorrect clauses can leak or hide customer data.

Before preparing or approving RLS clauses, use `preset-embedded-rls`.

Confirm:

1. Viewer population and tenant/account identity.
2. Dataset IDs and column names the clauses target.
3. The exact `rls_rules` values intended for guest-token claims.
4. Whether the clauses are additive to workspace-level RLS.
5. How the result will be validated without exposing unnecessary data.

Do not invent tenant identifiers, filters, dataset columns, or access rules.

# Guest Token Routing

Use this reference when an embedding task reaches guest-token creation or payload review.

Guest tokens are signed credentials for external embedded access. They must be handled by the focused security-sensitive skill.

Before guest-token creation, use `preset-guest-tokens`.

The guest-token endpoint is:

| Goal | Endpoint |
|---|---|
| Guest token | `POST /api/v1/security/guest_token/` |

Do not print signed guest tokens in logs, examples, PR comments, or handoff notes.

Do not create a token until the embedded dashboard UUID/resource, user identity claims, RLS clauses, token handling plan, and expiration expectations are explicit.

# Trusted Domains And Origins

Use this reference for allowed-domain and origin behavior in embedded dashboard configuration.

Allowed domains are part of embedded dashboard configuration and control where embedded dashboards are expected to be loaded from. They are not a replacement for guest-token authorization or row-level security.

## Review Checklist

Before creating or changing trusted domains, confirm:

1. The exact dashboard ID or slug.
2. The application origins that should embed the dashboard.
3. Whether wildcard domains are allowed by policy.
4. Whether staging, production, and other non-production origins should differ.
5. The rollback plan if an origin is too broad or breaks embedding.

## Troubleshooting

If embedding fails:

| Symptom | Check |
|---|---|
| `404` from embedded endpoints | Feature flag, dashboard embedded config, permissions |
| Browser blocks embed | Origin/domain mismatch, iframe policy, app URL mismatch |
| Guest token accepted but data wrong | Use `preset-embedded-rls` to review RLS clauses |
| Token missing or rejected | Use `preset-guest-tokens` to review payload and handling |

Do not broaden trusted domains without explicit approval. Broad domains can allow unintended applications to host embedded content when paired with valid tokens.