Skip to main content
An API key lets a script or a tool read one workspace’s brands as you. Agency plans call it an organization. It reads what you can read there, never changes anything, and stops working when you lose access, revoke it or it expires.

​
Create a key

  1. In Heralded, open Settings, choose You, 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 or organization, when you belong to more than one. A key reads one.
  4. Pick when it expires: 30 days, 90 days, 1 year or never. The default is 90 days.
  5. Copy the key. 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. If you signed in more than a day ago, Heralded asks you to sign in again first. An account holds at most 20 keys.

​
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. 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 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.