Skip to main content
An API key lets a script or a tool act in one workspace as you, with the access you choose. It stops working when you lose access, revoke it or it expires.

Create a key

  1. In Heralded, open the brand menu at the top of the rail, select the cog beside your name, Account settings, then API keys, and choose Create API key.
  2. Name the key after what will use it, such as Looker or Weekly export.
  3. Pick the workspace, when you belong to more than one. A key reads one.
  4. Choose Read only or Full access. The default is Read only.
  5. Pick when it expires: 30 days, 90 days, 1 year or never. The default is 90 days.
  6. Copy the key and choose Done. It starts with hrld_, and Heralded shows it only once and stores only a hash of it.
Any member who can read something in a workspace can create a key there. Creating one needs a recent sign-in or identity confirmation. If neither happened within the last two hours, Heralded opens Confirm it’s you so you can confirm without leaving the page. Account and security describes your options. An account holds at most 20 keys.

Access

API keys and assistant connections have two access choices: Full access permits writes, such as running Snapshots, only when your role can run work in the credential’s workspace. Otherwise a write answers forbidden, as Errors and limits describes. Your permissions are checked on every call. Existing keys and assistant connections keep read-only access. Create a new key to change its access, or reconnect an assistant and approve full access. A compatible assistant can also ask you for more access when a write is refused with insufficient_scope.

Use a key

Send the key as a bearer token on every request:
For a client that asks for a header rather than a token, the header is Authorization and its value is Bearer hrld_.... The MCP guide shows the setup for common MCP clients. New keys contain hrld_, 30 random base62 characters and a six-character CRC32 base62 checksum, 41 characters in total. Service tokens use hrld_svc_ with the same body, 45 characters in total. An invalid checksum is refused before a database lookup. Existing 48-character keys keep working. Treat a key like a password. Keep it in a secret store or an environment variable, not in code or a shared document.

What a key can read

  • The brands you can read in the key’s workspace, as GET /v1/brands lists them.
  • Your access is checked again on every request. If a role or grant changes, the key reads what you can read now.
  • A brand outside the workspace, or one you can no longer read, answers 404 not_found, the same as a brand that does not exist.
  • Once the workspace is archived, every REST request answers 409 workspace_archived, and an MCP tool call returns it as an error result; see Errors over MCP.

Revoke a key

The API keys page lists each key with its access, workspace, when it was created, when it was last used and when it expires. Revoke deletes the key, and its next request answers 401 invalid_token. An expired key answers the same way. A revoked or expired key cannot be restored; create a new one.