GET STARTED

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.

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

Read this page as Markdown

66 beta testing now