> ## Documentation Index
> Fetch the complete documentation index at: https://docs.heralded.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API keys

> Create, use and revoke the keys that read the Heralded API.

An API key lets a script or a tool read one [workspace's](/concepts/workspaces-and-brands#workspace) 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:

```bash theme={null}
curl -H "Authorization: Bearer hrld_..." https://api.heralded.ai/v1/brands
```

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](/connect-mcp) 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](/errors-and-limits#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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.