Skip to main content

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 mint scope ("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.

FieldWhat it does
tenantIdThe customer whose rows the viewer sees, decided on your server.
ttlSecondsHow long the token lasts, in seconds: one hour by default, cut to 24 hours if longer.
externalUserIdYour own id for the user, up to 128 characters without : or /, for your records.
timezoneThe viewer's time zone for dates, a name from GET /v5/admin/timezones such as America/Chicago.
themeIdThe theme the dashboard uses: default-light, default-dark, or a custom theme's id from the builder's theme editor. See Embed options.
permissionsActions to turn off, such as { "rows": false }; see Embed options.
attributesWith 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:

  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 codeWhat it meansWhat to do
401 API_KEY_INVALIDThe key is missing, wrong, or revoked.Check the X-Api-Key header. Create a new key if needed.
403 INSUFFICIENT_SCOPEThe key does not have the mint scope.Use a key with mint.
400 BAD_REQUESTThe 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_REQUESTtenantId 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_CHARSETexternalUserId holds : or /.Use another id for the user.
400 INVALID_EXTERNAL_USER_ID_LENGTHexternalUserId is over 128 characters.Use a shorter id.
422 INVALID_TIME_ZONEThe time zone is not one GOAT lists.Use a name such as Europe/Madrid.
404 TENANT_UNKNOWNThe tenant is not registered, or its id is not valid.Register it. See Tenants and access.
422 INVALID_TENANTWith automatic registration on, the id cannot be used.Check the id against the rules in Tenants and access.
403 TENANT_SUSPENDEDThe tenant is suspended.An admin reactivates it.
429 RATE_LIMITEDToo many requests for this key.Wait the seconds in Retry-After, then try again.
500 STORE_ERRORGOAT 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_DISABLEDThe 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.
GOAT documentation

Type to search.