Authentication

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

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.

Creating a key #

Keys are created in the Podzone app, on the 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 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:

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 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:

{
  "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.

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 page. A revoked key stops working at once.