# Authentication

> API keys, the difference between team and account keys, and the X-Podzone-Team header.

Every request to the Podzone API carries an API key, sent as a bearer token:

```bash
curl https://api.podzone.fm/api/v1/me \
  -H "Authorization: Bearer pzk_live_..."
```

A key that is missing, mistyped or revoked gets a `401` with the code `invalid_credentials`. The same keys work for the [MCP server](https://podzone.fm/docs/mcp).

## Creating a key

Keys are created in the Podzone app, on the [API keys](https://app.podzone.fm/api-keys) page. The key is shown once, when it is created; after that the app shows only its prefix.

Treat a key like a password. Keep it on a server, in an environment variable or a secrets manager — never in a browser, a mobile app or a repository. Anyone holding it can read your team's data and spend your account's limits.

## Team and account keys

A key is either **team-scoped** or **account-scoped**, and [`GET /api/v1/me`](https://api.podzone.fm/api/v1/docs#tag/identity/operation/me) says which in its `scope`.

A **team-scoped** key reaches one team. It carries that team itself, so nothing needs to be sent with each request. This is what a new key is unless you choose otherwise, and what most integrations want.

An **account-scoped** key reaches every team in the account. Each request that touches a team's data — its alerts, their matches, its webhook — must name the team in an `X-Podzone-Team` header:

```bash
curl https://api.podzone.fm/api/v1/alerts \
  -H "Authorization: Bearer pzk_live_..." \
  -H "X-Podzone-Team: 0199a1b2-c3d4-7e5f-8a9b-0c1d2e3f4a5b"
```

[`GET /api/v1/teams`](https://api.podzone.fm/api/v1/docs#tag/identity/operation/list_teams) lists the teams a key can reach, with the ids to send.

Omitting the header on an account-scoped key, or naming a team outside the account, returns a `422` that names the header:

```json
{
  "error": {
    "code": "invalid_input",
    "message": "One or more fields were invalid.",
    "fields": { "X-Podzone-Team": ["X-Podzone-Team must name a team in this account. ..."] }
  }
}
```

Sending the header with a team-scoped key does nothing, since that key's team is fixed. Search, podcasts, episodes and transcripts belong to no team, so those routes ignore the header for either kind of key.

## Limits

Limits are counted per **account**, not per key: every key in an account shares one budget. Every response says how much of it is left, in `X-RateLimit-*` headers. The numbers for each plan, and what to do with a `429`, are in the API reference's [rate limits](https://api.podzone.fm/api/v1/docs#section/Rate-limits).

## Replacing a key

To replace a key without downtime, create the new one, move your integration to it, and then revoke the old one on the [API keys](https://app.podzone.fm/api-keys) page. A revoked key stops working at once.