Skip to main content

Run GOAT

API keys

The keys your backend uses to call GOAT.

An API key is what your backend presents to GOAT to ask for viewer tokens or to send data. This page covers creating, rotating, and revoking keys. Only an admin can create or revoke a key; authors can see the list.

What a key can do​

Each key has one or more scopes:

ScopeThe app's hintWhat it allows
mintMint embed tokensAsking for viewer tokens. See Viewer tokens.
ingestPush and load dataSending rows to a Push API dataset, and loading data. See Push data from your application.
mintAuthorMint author-tier tokens for a tenantAsking for tokens for your customers' own authors, for a feature not yet usable from the embed script. Leave it off. See Tenant-author tokens for what these tokens can do.

A key with no scope selected can ask for viewer tokens, as if it had mint. Give each backend a key with only the scopes it needs.

No API key can call the tenant, grant, or settings parts of the API; those take a person's sign-in.

Create a key​

  1. Open the account menu, choose Admin, then the Keys tab.
  2. Choose Mint key.
  3. Under Name (optional), say what will hold the key, such as "Web app token endpoint".
  4. Under Scopes, select the scopes it needs.
  5. Choose Mint key.
  6. Copy the key under The key, then choose Done.

The key is shown only once. GOAT keeps only a fingerprint of it, so a lost key cannot be recovered: create a new one and revoke the old one.

A key looks like ak_<key id>_<secret>. Your backend sends it in the X-Api-Key header. Store it as a secret on your server, never in a web page, an app bundle, or a log.

The list of keys​

The Keys tab lists each key's Key ID, Name, Status (Active or Revoked), Scopes, and when it was created and last changed. It never shows a key's secret again.

Rotate a key​

There is no rotate button. To replace a key without downtime:

  1. Create a new key with the same scopes.
  2. Put the new key in your backend and deploy it.
  3. Revoke the old key.

An install can hold several active keys at once.

Revoke a key​

  1. In the Keys tab, choose Revoke on the key's row.
  2. Confirm with Revoke.

From then on, the key cannot get new viewer tokens or send data. Viewer tokens it already got keep working until they expire, which is within the token's lifetime: one hour by default, at most 24 hours. Dashboards, datasets, and access are not touched.

If a key may have leaked, revoke it at once, then create a new one.

Common problems​

What you seeWhat to check
Mint key and Revoke are grayed outYou are signed in as an author. An admin creates and revokes keys.
Your backend gets 401 API_KEY_INVALIDThe key is wrong or revoked.
Your backend gets 403 INSUFFICIENT_SCOPEThe key does not have the scope that request needs.
Your backend gets 429 RATE_LIMITEDThe key asked for more than 300 tokens in a minute. Reuse tokens until they expire.
GOAT documentation

Type to search.