# Authentication

> How the per-site read API key works, where to find it, how to rotate it, and why feeds are public but posts are not.

Mentionwell uses three credential types, each with a distinct prefix so they're never confusable:

| Credential | Prefix | Where it's used | Who issues it |
|---|---|---|---|
| **Reader API key** | `mw_read_` + 32 hex | Bearer token on every `/api/public/*` request and on outbound webhooks | Derived per-site from your site ID + the server's `READER_API_SECRET` |
| **Webhook signing secret** | `whsec_` + 48 hex | HMAC-SHA256 signing key for outbound webhooks | Derived per-site, same mechanism |
| **Personal access token (PAT)** | `mw_pat_` + random | Bearer token on authenticated dashboard endpoints when you call them outside the browser (CLI, automation) | Minted in the dashboard, scoped per token |

All three are tied to a single site (or, for PATs, a user). Nothing here gives cross-tenant access.

## Get your Reader API key

1. Open the Mentionwell dashboard and pick the site.
2. Click **Integration**, then **Connect with guided wizard** (or **Reconfigure delivery** if you're already connected).
3. The wizard's **Setup** step shows your Reader API key and webhook secret in a copy-button card.

Set the key on your destination site as `MENTIONWELL_API_KEY`. The key looks like `mw_read_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`.

## Use it

Every request to the post endpoints carries an `Authorization: Bearer <key>` header.

```bash
curl https://app.mentionwell.com/api/public/your-site-slug/posts \
  -H "Authorization: Bearer <MENTIONWELL_API_KEY>"
```

Without the header, you get a `401`.

## Why per-site

Each Mentionwell site has its own key. The key only authorises **reading published posts for that site**. It can't:

- write content
- delete content
- read drafts
- access another site
- access dashboard / admin endpoints

That makes it safe to ship the key into any single-tenant destination repo. If a key leaks, the worst case is "someone reads your already-public articles a bit faster".

## Public, no-auth endpoints

These are intentionally open so syndication tools (RSS readers, IndexNow, Google Search Console, AI crawlers) can ingest them:

- `GET /api/sites/{siteSlug}/feed.xml`
- `GET /api/sites/{siteSlug}/feed.json`
- `GET /api/sites/{siteSlug}/sitemap.xml`
- `GET /llms.txt`, `GET /llms-full.txt`, `/docs/*.md` (these docs)

## Rotation

The per-site key is derived deterministically from your site ID and a server-side `READER_API_SECRET`, so there is no per-site rotate button — by design, every key for the same site is the same value across reloads of the dashboard.

Two ways to rotate:

1. **Compromised one site only:** delete and re-create the site in Mentionwell. The new site gets a new ID and therefore a new key. Existing articles need to be regenerated.
2. **Rotate the global secret** (self-hosted Mentionwell): change `READER_API_SECRET` in your environment and redeploy. Every existing site's key changes; update each destination's `MENTIONWELL_API_KEY` accordingly.

For most users the key never needs to rotate — it's read-only per site, and a leak only lets someone read articles that are already public on your blog.

## Server-side only

Always read the key from a server-side env var. Never expose it via:

- `NEXT_PUBLIC_*` (Next.js)
- `VITE_*` (Vite)
- `PUBLIC_*` (Astro / SvelteKit)
- inline `<script>` constants
- the browser bundle

If you need posts client-side, proxy them through your own API route. Every framework quickstart shows the right pattern.

## What about webhooks?

Webhooks use a separate **HMAC signing secret** (`whsec_...` + 48 hex chars), not the Reader API key. See [Webhooks](/docs/webhooks) for the signing algorithm and headers Mentionwell sends.

## Personal access tokens (PATs)

PATs (`mw_pat_...`) are for calling **dashboard / write** endpoints outside the browser — CLIs, automations, the Connect-destination wizard if you're scripting it. Mint one in the dashboard under **Account → Personal access tokens**; scope it to `sites:read`, `sites:write`, or both. Treat PATs like passwords — they grant the same access your user account has within the scopes you assigned.

Reader API keys cannot replace PATs and vice versa. The server checks the prefix and rejects mismatches.


---

Canonical URL: https://mentionwell.com/docs/authentication
Live HTML version: https://mentionwell.com/docs/authentication
Section: Get started
Site index for AI ingestion: https://mentionwell.com/llms.txt
Full reference: https://mentionwell.com/llms-full.txt