# Viewer tokens

How your backend asks GOAT for a token for each viewer.

A viewer token lets one of your users see embedded dashboards as one of your customers, which GOAT calls a tenant. Your backend asks GOAT for it with an API key, and your page sends it with every request.

The examples use `https://analytics.example.com`; use your install's address, the one your users sign in to GOAT at.

## Before you start

- An API key with the `mint` scope ("Mint embed tokens"). See [API keys](../run-goat/api-keys.md).
- The tenant is registered, or automatic registration is on. See [Tenants and access](tenants-and-access.md).

## The request

```http
POST https://analytics.example.com/v5/tokens/embed
X-Api-Key: <your API key>
Content-Type: application/json

{
  "tenantId": "acme",
  "ttlSeconds": 3600,
  "externalUserId": "user-1842",
  "timezone": "America/Chicago",
  "themeId": "default-dark",
  "permissions": { "rows": false }
}
```

Only `tenantId` is required.

| Field | What it does |
|---|---|
| `tenantId` | The customer whose rows the viewer sees, decided on your server. |
| `ttlSeconds` | How long the token lasts, in seconds: one hour by default, cut to 24 hours if longer. |
| `externalUserId` | Your own id for the user, up to 128 characters without `:` or `/`, for your records. |
| `timezone` | The viewer's time zone for dates, a name from `GET /v5/admin/timezones` such as `America/Chicago`. |
| `themeId` | The theme the dashboard uses: `default-light`, `default-dark`, or a custom theme's id from the builder's theme editor. See [Embed options](embed-options.md#themes). |
| `permissions` | Actions to turn off, such as `{ "rows": false }`; see [Embed options](embed-options.md#turn-actions-off). |
| `attributes` | With automatic registration on, the tenant's attributes as `{ "plan": "enterprise" }`, set when GOAT registers it. |

Any other field is refused, so check the spelling and the case of each name.

## The answer

GOAT answers `201 Created`:

```json
{ "token": "eyJhbGciOi...", "tokenType": "Bearer", "expiresAt": "2026-11-09T15:04:05Z" }
```

If the theme you asked for cannot be used, GOAT still issues the token, without the theme, and adds a warning:

```json
{ "token": "eyJhbGciOi...", "tokenType": "Bearer", "expiresAt": "2026-11-09T15:04:05Z",
  "warnings": [{ "code": "THEME_DROPPED", "themeId": "th_123", "reason": "missing" }] }
```

## Serve it to the page

The snippet from Publish & share (see [Embed a dashboard](embed-a-dashboard.md#copy-the-snippet)) calls your endpoint at the path you put in it, with a plain `GET` from the page and no body. Your endpoint:

1. Identifies the user from your own sign-in, such as your session cookie.
2. Looks up which tenant they belong to.
3. Asks GOAT for a token, as above.
4. Returns the value of `token` alone, as plain text, with status `200`.

The snippet keeps the token and asks your endpoint again only when GOAT says it has expired. If your endpoint fails, the page tries twice more, after half a second and a second and a half, then shows "Your session ended and could not be renewed. Reload the page to continue."

## Errors

| Status and code | What it means | What to do |
|---|---|---|
| `401 API_KEY_INVALID` | The key is missing, wrong, or revoked. | Check the `X-Api-Key` header. Create a new key if needed. |
| `403 INSUFFICIENT_SCOPE` | The key does not have the `mint` scope. | Use a key with `mint`. |
| `400 BAD_REQUEST` | The body is not valid JSON, is over 4 KB, or has a field GOAT does not know. | Check the body and the field names. |
| `422 INVALID_TOKEN_REQUEST` | `tenantId` is missing, or a field's value is not allowed. | Read the error body's `message`, which names the field. |
| `400 INVALID_EXTERNAL_USER_ID_CHARSET` | `externalUserId` holds `:` or `/`. | Use another id for the user. |
| `400 INVALID_EXTERNAL_USER_ID_LENGTH` | `externalUserId` is over 128 characters. | Use a shorter id. |
| `422 INVALID_TIME_ZONE` | The time zone is not one GOAT lists. | Use a name such as `Europe/Madrid`. |
| `404 TENANT_UNKNOWN` | The tenant is not registered, or its id is not valid. | Register it. See [Tenants and access](tenants-and-access.md). |
| `422 INVALID_TENANT` | With automatic registration on, the id cannot be used. | Check the id against the rules in [Tenants and access](tenants-and-access.md#tenant-ids). |
| `403 TENANT_SUSPENDED` | The tenant is suspended. | An admin reactivates it. |
| `429 RATE_LIMITED` | Too many requests for this key. | Wait the seconds in `Retry-After`, then try again. |
| `500 STORE_ERROR` | GOAT could not read or write its records, for example while registering a tenant automatically. | Try again. If it persists, ask whoever runs GOAT. |
| `503 EMBED_DISABLED` | The install has no token signing set up. | Ask whoever runs GOAT. |

## Limits

- Each API key may ask for 300 tokens a minute. Reuse a token until it expires rather than asking for one per page view.
- A token lasts at most 24 hours. A viewer who keeps a page open longer gets a fresh token from your endpoint without noticing.

## Security rules

- Decide `tenantId` on your server. Never take it from the browser, a query string, or a form.
- Keep the API key on your server, out of the page, your app's bundles, and your logs.
- A token is a pass to one tenant's data for its lifetime. Give it only to that tenant's users, and keep its lifetime as short as your pages allow.
