Authentication
API keys, scopes, live and test mode, and how AI agents connect over MCP without one.
The REST API checks who's calling with an API key. Zapier, n8n, your own code and your scripts all use one.
- You make keys in the dashboard. They belong to your organization.
- Each key carries a list of what it's allowed to do. Each item on that list is a scope.
- AI agents don't use a key. They connect over MCP by signing in (below).
API and MCP access come with every plan, the free trial included.
Creating a key
- In the dashboard, open Settings, then API keys.
- Name the key after what will hold it, like "Production server" or "Zapier".
- Read the short summary beside Create key. It says what the key can and can't do.
- By default a key can do everything. To narrow it, choose Limit this key and pick scopes. The summary follows your choice.
- Press Create key, then copy the key.
You see the key exactly once, with the same summary beside it. We only store a scrambled fingerprint of it (a hash), so we can't show it again.
Keys look like rail_live_… or rail_test_….
A test key is a live key with a different prefix. It reads and writes the same data as a live one: the same partners, commissions and payouts. Every response carries X-Rail-Livemode: false. That header labels the answer. It doesn't wall off any data.
So a rail_test_ key used from staging creates real partners and real commissions in your real program. Want a place to experiment where nothing counts? Make a second organization and create a key there.
Send the key in the Authorization header, after the word Bearer (a bearer token):
curl https://api.affiliaterail.com/v1/programs \
-H "Authorization: Bearer rail_live_..."Scopes
A key holds one or more scopes. Pick the smallest set that does the job. You can always create another key.
| Scope | Allows |
|---|---|
read | Read every object in the organization |
write | Create, update and delete every object (includes every narrower write scope), and mint partner sign-in links |
partners:write | Partners, groups, tags, applications, links and coupons |
commissions:write | Clicks, customers, sales, refunds, commissions and commission rules |
payouts:write | Payout batches and marking payouts paid |
webhooks:write | Webhook endpoints |
mcp:read | Read-only access for a connected model (MCP) |
mcp:write | Every write tool a connected model has: program settings, branding, commission rules, groups, partner links, coupons and clearing sample data, plus the review queues and partner invites. Read-only over REST |
Any write scope includes read, and read means everything in your organisation. So a key with only partners:write can still read sales, commissions and payouts. Pick read on its own for a key that should only look.
Ask for more than a key holds and you get a 403. It names the scope the request needed and the scopes the key holds, so you know the fix.
One action sits on no narrow scope: POST /v1/partners/{id}/sso. It makes a link that signs a
partner into their portal. That's a live session, not a record, so only a key holding write can
make one. A leaked partners:write key can't open a partner's portal.
Revocation
Revoke a key under Settings, API keys. It stops working on its next request, so everything that sends it is cut off at once.
If a key leaks, revoke it first. Then create its replacement.
How AI agents connect
An AI agent doesn't need a key.
- Add
https://mcp.affiliaterail.com/mcpto Claude, ChatGPT, Claude Code, Cursor, VS Code or Codex. - AffiliateRail opens in your browser. Sign in the way you always do.
- Press Allow.
The agent gets a short-lived token. It lasts an hour and renews on its own. You never see a key, so you can't leave one in a chat.
Each connection is listed under Settings, API keys, Connected agents. Press Disconnect next to one and it stops on its next request. Removing the connector inside your agent ends it too.
Connect your assistant or editor walks through each client. MCP security explains how it works.
Webhook signing
A webhook is a message we send to your server when something happens. Each one is signed, so your server can prove it came from us.
- The signing secret is a
whsec_…value, one per endpoint. - It's separate from your API keys.
- You see it once, when you create the endpoint.
See Webhooks.