# What’s Trending API authentication

The public product API uses workspace-scoped Bearer API keys. It does not advertise OAuth client credentials, delegated OAuth scopes, anonymous API access, or a public sandbox.

## Pick the supported method

Use an API key only for server-side REST or MCP calls. Browser sign-in, subscription checkout, billing management, and API-key administration use the signed-in web application and are not API-key operations.

## Eligibility

API and MCP access require an active Pro subscription. The Free preview and Weekly plan do not include agent API access. See [pricing](https://whatstrending.cc/pricing.md).

## Create a credential

1. Sign in to [the What’s Trending application](https://app.whatstrending.cc/).
2. Complete workspace setup.
3. Activate Pro.
4. Open **Settings → Agent access**.
5. Create a key with a descriptive label.
6. Copy the key when it is shown. The service stores only a hash and cannot show the full key again.

Keys begin with `wt_live_`. Never publish a live key in a document, query string, browser bundle, source repository, prompt, transcript, analytics event, or log.

## Send the credential

Use the standard HTTP Authorization header on every protected REST or MCP request:

```http
Authorization: Bearer wt_live_YOUR_KEY
```

REST example:

```bash
curl https://api.whatstrending.cc/v1/trends?days=30 \
  -H "Authorization: Bearer wt_live_YOUR_KEY"
```

MCP discovery calls such as `tools/list` are public. Authenticated `tools/call` requests require the same Bearer header.

## Credential scope

Each key is scoped to one What’s Trending workspace. It can read that workspace’s configuration, ranked trends, and stored source evidence. It can also trigger a live scan when the active plan permits it. It cannot read another workspace, administer users, create other API keys, change a subscription, or open the billing portal.

## State-changing calls

`POST /v1/scans` and the MCP `run_scan` tool collect and persist new evidence. They are not read-only. Confirm the user intends to refresh the workspace before calling either surface. Pro agent-triggered scans are limited to once per hour per workspace.

## Errors

- `401 Unauthorized`: the Bearer header is missing, malformed, invalid, or revoked.
- `403 Forbidden`: the key is valid but the workspace does not have active Pro API access.
- `429 Too Many Requests`: a scan was requested before the hourly interval elapsed.
- Other `4xx` responses indicate an invalid route, method, or input.
- `5xx` responses indicate an unexpected service error; retry reads with bounded backoff. Do not retry a state-changing scan blindly.

## Revoke or rotate a key

Open **Settings → Agent access**, create a replacement if needed, update the approved server-side secret store, verify the replacement, and revoke the old key. A revoked key stops authorizing future API and MCP calls.

## Security boundaries

- Keep the full credential in an approved server-side secret store.
- Redact the credential from logs and model-visible output.
- Do not place it in a URL.
- Do not ask a user to paste a live key into public chat.
- Inspect and cite original source URLs before presenting an evidence-based claim.
- Treat missing metrics as unavailable rather than zero.

## Related documentation

- [OpenAPI 3.1 contract](https://whatstrending.cc/openapi.json)
- [Agent integration guide](https://whatstrending.cc/for-agents)
- [MCP discovery](https://whatstrending.cc/.well-known/mcp)
- [Agent skill](https://whatstrending.cc/.well-known/agent-skills/whatstrending-research/SKILL.md)