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

# API keys and secrets

> Authenticate the CLI, SDK, and API with API keys, and give runs the credentials they need: environment variables, personal secrets, and your own model provider keys.

HUD uses two kinds of credentials. **API keys** prove to HUD who you are. **Secrets** and
**provider keys** are credentials your runs use: logins for the services an environment talks to,
and keys for the model providers your agents call.

## API keys

An API key authenticates the CLI, SDK, [REST API](/platform/rest-api), and
[Platform MCP](/platform/mcp) as you, in the team where you created it. Set it as `HUD_API_KEY`.
Its usage counts as yours, and the [Usage](/platform/billing#usage) page can break spend down by key.

To create one, open **Settings** → **API keys** and select **Create new API key**. Give it a name
that is unique in the team and choose when it expires: no expiration, 30, 90, or 180 days, or one
year. Admins can create a key for another member. **Save your key** shows the value once; copy it
then, because HUD can't show it again.

Each key shows when it was created and last used, and what it spent this month. Its menu can:

* **Copy prefix** or **Copy key ID**, to identify the key elsewhere.
* **Rename key**.
* **Add spend limit**, to cap or watch what the key spends. See [spend limits](/platform/billing#spend-limits).
* **Revoke key**. It stops working immediately.

**Show revoked** lists revoked and expired keys. Admins also see every member's keys. Removing
someone from the team revokes their keys.

### The Default key

Every member also has a **Default key**, which HUD manages. It is the key that work HUD runs for
you carries: hosted runs you start, QA agents, and templates that take a `hud_api_key` argument,
which HUD fills in when the run starts. You can't view its value, and tasks can't set
`hud_api_key` themselves.

The Default key can't manage team members, secrets, or provider keys, and the
[API rate limit](/platform/limits#api-rate-limits) doesn't apply to it. **Rotate platform key**
replaces it, and the previous value stops working immediately.

## Credentials for runs

Code in a run's sandbox gets its credentials as environment variables, from up to three places:

| Source | Set in | Applies to | Use it for |
| - | - | - | - |
| **Environment variables** | The environment's **Settings** | Every run of that environment | What the environment needs to work, such as the login for the site it drives. See [runtime variables](/platform/environments#configure-runtime-variables). |
| **Personal secrets** | **Settings** → **Secrets** | Every run you start | Credentials your own runs need, such as your account on an external service. |
| **Values from your code** | The SDK, when it starts an environment | That run | Settings for one run. |

When the same name is set in more than one place, the environment variable wins over a personal
secret, and a personal secret wins over a value from your code.

To add a personal secret, enter a name such as `SERVICE_TOKEN` and its value. Values are masked after
saving, and only you can see or change your secrets.

## Bring your own provider keys

By default, agents call models through HUD's [inference gateway](/v6/reference/agents#built-in-agents) on HUD's
provider accounts, and you pay the model's price in credits. To use your own account with a model
provider instead, add its key in **Settings** → **BYOK**:

* **Personal** keys apply to the requests you make.
* **Team** keys, which admins manage, apply to every member who has no personal key for that
  provider. Your personal key takes precedence.

Requests sent with your key:

* Are billed by the provider to your account. HUD charges a fee of 5% of what the request would
  have cost through HUD's account, and nothing for requests that fail.
* Use your provider account's capacity instead of HUD's. HUD's
  [per-minute limit on model calls](/platform/limits#model-calls) still applies.
* Still need credit to start, and count toward [spend limits](/platform/billing#spend-limits),
  with the fee as their cost.
* Appear on the Usage page under **Provider credential**.

Provider keys stay on HUD's servers and are never placed in a sandbox. Use them when agents call
models through HUD. If code inside a sandbox calls a provider directly, give it the key as a
personal secret or an environment variable instead.


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