Authentication
API keys, scopes, live and test mode, and how assistants connect over MCP.
Everything programmatic, the REST API and the MCP server alike, authenticates with an API key. Keys belong to your organization, are minted in the dashboard, and carry scopes that say what they may do. API and MCP access is part of every plan, the free trial included.
Creating a key
- In the dashboard, open Settings, then API keys.
- Choose New key, name it after what will hold it ("Production server", "Claude"), and pick its scopes.
- Copy the key. It is shown exactly once; only a hash is stored.
Keys look like rail_live_… or rail_test_…. Both work against the same organization; a test key sees the same program but stamps every response with X-Rail-Livemode: false, so a staging environment can never quietly mix its data into production's.
Send the key as 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 narrowest set that does the job; you can always mint another key.
| Scope | Allows |
|---|---|
read | Read every object in the organization |
write | Create, update and delete every object (includes every narrower write scope) |
partners:write | Partners, groups, tags, applications, links, coupons and partner sign-in links |
commissions:write | Clicks, customers, sales, refunds, commissions and flows |
payouts:write | Payout batches and marking payouts paid |
webhooks:write | Webhook endpoints |
mcp:read | Read-only access for a connected model (MCP) |
mcp:write | Approve, reject and invite from a connected model; read-only over REST |
Any write scope implies read. A request beyond the key's scopes returns a 403 naming the scope it needed and the scopes the key holds, so the fix is never a guess.
Revocation
Revoke a key under Settings, API keys and it stops working on its next request. Everything connected through it, servers and assistants alike, is cut off at once. If a key ever leaks, revoke it first and mint its replacement second.
How assistants connect
The MCP server never sees a pasted key inside the assistant. When you add https://mcp.affiliaterail.com/mcp to Claude or ChatGPT, the assistant is sent to an AffiliateRail page where you paste the key once; it is checked, never stored, and the assistant receives a short-lived token instead (an hour, refreshed automatically, dead the moment the key is revoked). Connect Claude or ChatGPT walks through it, and MCP security explains the machinery.
Webhook signing
Webhooks authenticate in the other direction: every delivery is signed with an endpoint-specific secret so your server can prove it came from us. That secret is a whsec_… value, separate from API keys, shown once when the endpoint is created. See Webhooks.