Embed in your product
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
mintscope ("Mint embed tokens"). See API keys. - The tenant is registered, or automatic registration is on. See Tenants and access.
The request
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. |
permissions | Actions to turn off, such as { "rows": false }; see Embed options. |
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:
{ "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:
{ "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) calls your endpoint at the path you put in it, with a plain GET from the page and no body. Your endpoint:
- Identifies the user from your own sign-in, such as your session cookie.
- Looks up which tenant they belong to.
- Asks GOAT for a token, as above.
- Returns the value of
tokenalone, as plain text, with status200.
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. |
422 INVALID_TENANT | With automatic registration on, the id cannot be used. | Check the id against the rules in Tenants and access. |
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
tenantIdon 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.