Using API tokens

An API token is a long-lived credential you generate in your dashboard and pass on the Authorization header when you call our API from outside a browser. Two common scenarios:

• A CI pipeline that publishes your site after your content team approves a Notion automation.
• A Zapier integration that posts a project comment whenever a Slack message lands in a specific channel.
• A custom internal dashboard that pulls your latest invoice into your team’s ops console.

In every case, the token is the API’s answer to "I’m not a person clicking buttons; I’m a machine".

Creating a token.

1. Open API tokens in your dashboard.
2. Click Create token and give it a clear name — CI pipeline, Zapier — Slack to MM, Internal ops dashboard. Future-you will thank present-you when you’re trying to figure out which token is which.
3. Pick the scopes the token needs. A scope is a capability — publish, messages, files, domain, billing.read. A token without the right scope can’t use the matching endpoint, even if your account would otherwise allow it. Pick the narrowest set that does the job; you can always create a second token with broader scopes later.
4. Pick an expiry. We default to 1 year. You can also pick 1 month, 6 months, or Never. Shorter is safer; Never is convenient. Pick what your operations cadence supports.
5. Click Create token.

We’ll show you the full token once. It looks like mm_pat_ followed by 32 characters — for example, mm_pat_A3B9XYZ2P4QR5STVW6XY78AB2C3DE.

Important: copy it now. We don’t store the plaintext anywhere on our side — only a hash for verification and a short prefix for identification. If you close that dialog without copying the value, the only path forward is revoke + create a new one.

Using a token.

Pass it on the Authorization header with the Bearer scheme:

`` curl -X POST https://app.mantelmarketing.com/api/publish \ -H "Authorization: Bearer mm_pat_YOUR_TOKEN_HERE" \ -H "Content-Type: application/json" \ -d '{"projectId":"YOUR_PROJECT_UUID"}' ``

That’s it. The endpoint that previously required a Clerk session cookie now also accepts the Bearer token — same permission rules, just a different way of saying who you are.

Security checklist.

• Never commit a token to git. Treat it like a password. Use environment variables, GitHub Actions secrets, Vercel project env vars, or whatever your CI provider uses for secrets.
• Rotate periodically. Even with no known compromise, rotating tokens once or twice a year limits the blast radius of an old laptop someone forgot to wipe.
• One token per integration. Don’t share one token between three different systems. If you need to revoke for one, you don’t want to break the other two.
• Use the narrowest scopes. A "Zapier — post messages" token doesn’t need the publish scope. A "CI publish" token doesn’t need messages.

Revoking a token.

Open API tokens, find the token in the list, click Revoke. The token stops working immediately — any client using it will start getting 401 Unauthorized on the next request. Revocation is final; you can’t un-revoke. Create a fresh token if you need to rotate.

Why we don’t let API tokens create more API tokens. The token CRUD endpoints (create, revoke) require a Clerk dashboard session — you can’t mint a new token by passing an existing token on the Authorization header. This stops a leaked token from compounding into a deeper compromise; the worst-case for any token leak is bounded by whatever scopes the token already carries.