Get started
Quickstart
From a running install to your first embedded dashboard.
This guide takes you from a running GOAT install to a dashboard showing inside a page of your own application, filtered to one customer. It takes about 30 minutes.
Before you start
You need:
- A running GOAT install, and its address, such as
https://analytics.example.com. See Install GOAT. - An Admin sign-in to that install. An Author's sign-in works for every step except creating the API key in step 5. That includes the API call in step 6.
- Your own sign-in token, for the one-time API call in step 6. The app does not yet show that token, and these docs do not yet say how to get it.
- A BigQuery table that GOAT can read, with a column that says which customer each row belongs to. If GOAT cannot read it, the dataset step names the access it is missing; see Give GOAT access to your data.
- A backend you can add one endpoint to, and a web page in your application to put the dashboard on.
- One customer id from that column, to test with. This guide calls it
acme. A customer id can hold letters, digits,-, and_, starts with a letter or digit, and is at most 64 characters. Ids with spaces, dots, or@cannot be used. If the column holds numbers, write the id without leading zeros.
1. Create a dataset
- Sign in to GOAT and open Datasets.
- Choose New dataset, then BigQuery table or view.
- Pick your table and choose Continue.
- On Name and access, name the dataset. Under Tenant key, select the column that holds your customer ids. GOAT may suggest one.
- Leave "How GOAT reads it" at Live connect. GOAT then reads the table where it is, with nothing copied.
- Choose Create dataset.
The tenant key is what keeps each customer to their own rows. See Key concepts.
2. Create a collection and attach the dataset
- Open Collections and create a collection. Give it a name.
- In the collection, open the Datasets tab and choose Attach dataset.
- Pick the dataset from step 1 and attach it.
3. Build a dashboard
- In the collection's Dashboards tab, choose New dashboard.
- Give it a name. Leave Tenant access at Visible.
- In the builder, pick your dataset, then open the Data panel on the left.
- Drag a column onto the canvas. GOAT makes a chart from it: a number column gives a single big number, a date column a line over time, and any other column a bar chart.
- Drag two or three more columns to fill the dashboard.
The builder saves as you go.
4. Publish the dashboard
- In the builder, choose Publish in the top bar, then the Publish button in the panel that opens. Naming the version is optional.
- GOAT closes the builder and opens the dashboard's page. Choose Publish & share there.
- Under "Choose who can see it", leave the level at Visible. This gives every customer access.
- Under "Put it on your site", choose Copy. Keep the snippet for step 8.
5. Create an API key
Your backend uses an API key to ask GOAT for viewer tokens. The key is a secret and stays on your server.
- Open the account menu and choose Admin, then the Keys tab.
- Choose Mint key. Name it after your backend, and under Scopes select
mint("Mint embed tokens"). - Copy the key. It is shown only once.
6. Register your customer
GOAT issues viewer tokens only for customers it knows. Register acme once by sending its id to the install's tenant API:
POST https://analytics.example.com/v5/admin/tenants
Authorization: Bearer <your own sign-in token, as an Admin or Author>
Content-Type: application/json
{ "tenantId": "acme" }
GOAT answers 201 Created. The API key from step 5 cannot make this call; the tenant API takes an Admin's or Author's own sign-in. The app does not yet offer a way to register customers. A page on getting your sign-in token, Get an operator token, is not written yet. For registering customers once you are live, see Tenants and access.
7. Add a token endpoint to your backend
Add an endpoint to your backend that returns a viewer token for the signed-in user's customer. It calls GOAT with the API key from step 5:
POST https://analytics.example.com/v5/tokens/embed
X-Api-Key: <your API key>
Content-Type: application/json
{ "tenantId": "acme" }
GOAT answers 201 Created with the token, valid for one hour:
{ "token": "eyJhbGciOi...", "tokenType": "Bearer", "expiresAt": "2026-11-09T15:04:05Z" }
Your endpoint returns the value of token alone, as plain text. The snippet calls your endpoint from the page with a plain GET and no body, so your endpoint finds the user from your own sign-in, such as your session cookie. Always decide the tenant on your server, never from anything the browser sends.
See Viewer tokens for the full request and answer.
8. Put the dashboard on your page
Paste the snippet you copied in step 4 into your page. It loads the embed script from your install, places the dashboard, and asks your endpoint for a token. Replace /my-backend/embed-token in the snippet with the path of your endpoint from step 7. The full snippet, and what each part does, is in Embed a dashboard.
Open the page. The dashboard draws, showing only acme's rows.
If the dashboard does not show
If the dashboard shows "Your session ended and could not be renewed. Reload the page to continue.", look first at what GOAT answered your backend in step 7.
| What you see | What to check |
|---|---|
Your backend gets 404 TENANT_UNKNOWN | The customer is not registered. Do step 6 with the same id. |
Your backend gets 401 API_KEY_INVALID | The API key is wrong or revoked. Mint a new one, step 5. |
Your backend gets 403 TENANT_SUSPENDED | The customer is suspended. Test with another customer, or have an Admin reactivate it. See Suspend, reactivate, or remove a tenant. |
The page gets 403 ORIGIN_DENIED | Check whether your install limits which sites may embed. If it does, an Admin adds your page's exact address to the install's list. See Allowed sites. |
| "This embed has no token provider." | Check that the snippet's script block comes directly after the dashboard element. |
| Your backend got a token, but the dashboard still ends with the session message | Check that your endpoint returns only the token value as plain text, not the whole answer. |
| "This dashboard is not available. It may have been removed, or you may not have access to it." | Check that the dashboard is published and its tenant access is not None. |
| Charts with no rows | Check that the tenant id matches the values in your tenant key column exactly. |
Next steps
- Build a dashboard: text, filters, tabs, and themes.
- Embed a dashboard: all the embed options.
- Tenants and access: give and take away access per customer.