---
title: "Authentication. Metadata Developer Docs"
url: https://metadata.io/developers/authentication
description: "Generate API keys, set scopes, and authenticate MCP requests to Metadata."
source: metadata.io
---

# Authentication

All Metadata MCP requests are authenticated with a bearer token scoped to a single account. Keys are minted from the app, stored server-side only, and can be rotated or revoked at any time.

**Governed execution:** Metadata has 299 public G2 reviews and the MCP workflow keeps campaign work reviewable before spend moves.

## Mint an API key

1. Sign in at [platform.metadata.io](https://platform.metadata.io)
2. Open **Settings → API Keys**
3. Click **Create Key**, name it after the agent that will use it (`claude-code-gil`, `hermes-prod`, `paperclip-sandbox`)
4. Set scopes (see [below](https://metadata.io#scopes)) and copy the token, it's shown exactly once

**Keys are shown once.** If you lose a key, rotate it rather than contacting support. Treat tokens like passwords, never commit to git, never log them, never paste into chat.

## Scopes

Keys can be scoped to limit blast radius. If a key only needs analytics, don't grant launch permissions.

| Scope | Grants | Destructive |
|---|---|---|
| `read:all` | All `get_*`, `search_*`, `list_*`, `*_stats`, `*_insights` tools | No |
| `write:audiences` | Create, update, archive audiences & target groups | No (reversible) |
| `write:creatives` | Generate/upload creatives, build ads | No |
| `write:campaigns` | Create & edit campaigns in `Draft`, excluding launch | No |
| `launch:campaigns` | `launch_campaign`, `manage_campaign`, real spend begins | Yes |
| `write:integrations` | Connect/disconnect channels & CRMs | Yes |
| `admin:*` | Account impersonation, billing, user mgmt | Yes |

## Using the key

### As an environment variable

The MCP client reads the key from `METADATA_API_KEY` by default:

### In Claude Code

Add to your `~/.config/claude-code/mcp.json`:

## Multi-account access

If your user has access to multiple Metadata accounts (agencies, holding companies), call `list_user_accounts` first and include `X-Account-ID` on subsequent requests:

## Key rotation

Best practice is to rotate keys quarterly, and immediately on any of:

- Employee or contractor offboarding
- Suspected key leak (logs, shared screen, repo commit)
- Scope expansion or reduction for the agent

Rotation is atomic, the old key stays valid for **15 minutes** after a new one is issued, so you can deploy the new key without downtime. Older keys are hard-revoked after the grace window.

## Auth errors

| HTTP | Code | Meaning |
|---|---|---|
| `401` | `missing_key` | No `Authorization` header |
| `401` | `invalid_key` | Key is revoked, rotated out, or malformed |
| `403` | `scope_denied` | Key is valid but lacks the scope for this tool |
| `403` | `account_mismatch` | `X-Account-ID` not accessible to this user |
| `402` | `insufficient_credits` | Credit balance is zero, top up or upgrade tier |

**Next:** with a key in hand, [connect Metadata to your MCP client](https://metadata.io/developers/installation.html), or jump straight to [shipping your first campaign](https://metadata.io/developers/guides/first-campaign.html).