programmatic-filters

The saved excerpt is a snapshot from when this skill was listed. The external source remains the complete and most current version.

---
name: programmatic-filters
description: Control which data each viewer sees in an embedded Domo dashboard/card via server-side programmatic filters and dataset switching. Covers the OAuth → embed token flow, standard filters, SQL filters (OR/BETWEEN/LIKE), per-dataset targeting, datasetRedirects for multi-tenant architectures, and token size limits. Use for any per-viewer, per-role, or per-tenant data restrictions at embed time. Not for client-side JS API filtering (use jsapi-filters).
---

# Domo Programmatic Filtering

Control what data each viewer sees in embedded Domo content via server-side filters and dataset switching. Enforced by Domo — end users can't bypass. For client-side filtering, see `jsapi-filters`.

## How It Works

A proxy user (service account) acts on behalf of all viewers. Your server:

1. Authenticates with Domo (OAuth client credentials → **access token**)
2. Requests an **embed token** with viewer-specific filters
3. Returns the token to the client, which POSTs it to an iframe

## Prerequisites

- Domo API client with `CLIENT_ID` and `CLIENT_SECRET` (developer.domo.com > My Account > New Client)
- Embed ID (5-char ID from the embed dialog, not the page URL)
- Dataset column names/IDs for filtering

**All auth must happen server-side** (CORS restrictions). Never expose credentials client-side.

## The Embed Token Flow

### Step 1: Get an Access Token

```
POST https://api.domo.com/oauth/token?grant_type=client_credentials&scope=data%20audit%20user%20dashboard
Authorization: Basic base64(CLIENT_ID:CLIENT_SECRET)
```

**Node.js:**
```typescript
const credentials = Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString('base64')

const response = await fetch(
  'https://api.domo.com/oauth/token?grant_type=client_credentials&scope=data%20audit%20user%20dashboard',
  {
    method: 'GET',
    headers: { Authorization: `Basic ${credentials}` }
  }
)

const { access_token } = await response.json()
```

**Python:**
```python
import requests
from base64 import b64encode

credentials = b64encode(f"{CLIENT_ID}:{CLIENT_SECRET}".encode()).decode()

response = requests.get(
    "https://api.domo.com/oauth/token",
    params={"grant_type": "client_credentials", "scope": "data audit user dashboard"},
    headers={"Authorization": f"Basic {credentials}"}
)

access_token = response.json()["access_token"]
```

### Step 2: Request an Embed Token with Filters

Use the access token to request an embed token, including your filters in the `authorizations` payload:

**For dashboards:**
```
POST https://api.domo.com/v1/stories/embed/auth
Authorization: Bearer {access_token}
Content-Type: application/json
```

**For cards:**
```
POST https://api.domo.com/v1/cards/embed/auth
Authorization: Bearer {access_token}
Content-Type: application/json
```

**Payload structure:**
```json
{
  "sessionLength": 1440,
  "authorizations": [
    {
      "token": "<embed_id>",
      "permissions": ["READ", "FILTER", "EXPORT"],
      "filters": [],
      "policies": []
    }
  ]
}
```

- `sessionLength`: Token validity in minutes (1440 = 24 hours)
- `token`: The embed ID for the dashboard or card
- `permissions`: Array of granted permissions — `READ`, `FILTER`, `EXPORT`
- `filters`: Array of standard filter objects (see below)
- `policies`: Array of PDP policy IDs to apply (optional)

The response includes an `authentication` property containing the embed token.

### Step 3: Render the Embed

Submit via hidden POST form targeting an iframe. Dashboard: `https://public.domo.com/embed/pages/{embed_id}`, Card: `https://public.domo.com/cards/{embed_id}`

```html
<iframe id="domo-embed" name="domo-embed" width="100%" height="600"></iframe>

<form id="embed-form" action="https://public.domo.com/embed/pages/{embed_id}" method="POST" target="domo-embed">
  <input type="hidden" name="embedToken" value="{embed_token}" />
</form>

<script>document.getElementById('embed-form').submit();</script>
```

POST submission prevents the token from appearing in URLs or