# 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's public API uses a single mechanism: a **per-site Bearer token** on the post endpoints.

## Get your key

1. Open the Mentionwell dashboard.
2. Pick the site.
3. Click **Ship**. The API key is shown there — it looks like `bgo_read_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx`.
4. Click **Reveal** + **Copy**.

Set it on your destination site as `MENTIONWELL_API_KEY`.

## Use it

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

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

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_...`), not the API key. See [Webhooks](/docs/webhooks).


---

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