Routy

Which token works where

Routy has two kinds of token you can hand to a script, a service or an AI assistant. They are made in different places, they are sent differently, and they are accepted by different parts of the API. Mixing them up is the most common reason an integration that "has a valid token" keeps getting refused.

API token Personal access token
Made in Settings → API tokens (account admins only) Your account menu → MCP & Access Tokens (every user)
Belongs to The affiliate. Keeps working whoever comes and goes You. Acts as you, never with more access than you have
Looks like A long string of letters, digits, +, / and = Starts with rpat_
Send it as Authorization: ApiKey <token> Authorization: Bearer rpat_… (or ApiKey rpat_…)
Guide API tokens MCP & Access Tokens

A third kind, the connected app, is what Claude or ChatGPT gets when you add Routy as a connector and click Allow. There is nothing to copy, and it only works for that assistant.

Send each token the right way

An API token must be sent with ApiKey, never with Bearer.

Authorization: ApiKey Qk9vM3J5VGtwc2ZYMmJ6dUx3PT1leGFtcGxl1A8=

Bearer is for personal access tokens and for a signed-in session. An API token sent as Bearer is read as a session, fails, and comes back as a plain 401 with no explanation.

A personal access token is accepted either way:

Authorization: Bearer rpat_…
Authorization: ApiKey rpat_…

Where each one is accepted

What you're calling API token Personal access token Connected app
The Routy API (/v1/…): reports, accounts, links, events and the rest Yes, within its permissions Yes, within its permissions No (401)
The AI assistant connector (https://mcp.routy.app/mcp) Yes, if it has Reports · Read Yes, if it has reports.read Yes
Creating or revoking personal access tokens No (403) No (403) No (403)
Creating or deleting API tokens Only a token with account-admin (Full access) Only a token with account-admin No (401)
Your own user: profile, password, in-app alerts, master password email No (403) No (403) No (401)
The older API, at paths without /v1/ No (401) No (401) No (401)

Three rules follow from the table:

  • Personal access tokens are managed only by you, signed in. No token, of any kind, can create, edit or revoke one.
  • Your own user's settings need you, signed in. A token, even a personal one, can't change a password or a profile. For "who am I?" with an API token, ask for your account (/v1/my/account), not your user.
  • The older API (paths without /v1/) takes neither kind of token. It accepts only a signed-in session. If an integration is calling an address without /v1/, move it to the /v1/ equivalent before giving it a token.

Choosing an affiliate

If you work on more than one affiliate, the two tokens behave differently:

  • An API token always works on the one affiliate it was made in. An x-affiliate-id header is ignored, not refused. If a request with an API token returns another affiliate's data than you expected, this is why: make the token in the affiliate you want.
  • A personal access token that can reach several affiliates must say which one, on every request, with the x-affiliate-id header. Leave it out and the request is refused with a 400 that lists the affiliates the token can use. A token limited to one affiliate uses it automatically.

Reading a refusal

You get Most likely cause Fix
401 with an empty body An API token sent as Bearer; a token sent to the older API (no /v1/); a connected app's access used outside the assistant; or the token expired or was deleted Check the header and the address against the tables above, then the token's status
403 "this endpoint is not available with API key authentication" Any token, including a personal access token despite the wording, used for something that needs you signed in Do it signed in
403 on any other request The token is valid but lacks the permission Give it the permission (personal access token: edit it; API token: make a new one)
403 "this token cannot act on the selected affiliate" A personal access token asked for an affiliate it wasn't given Pick an affiliate the token has, or make a token that has it
400 "this token reaches several affiliates; choose one with the x-affiliate-id header" A personal access token for several affiliates, without the header Add x-affiliate-id

A 401 never says which rule was broken, so check the header form first: it is the most common cause.

When to contact support

  • A token is sent the right way, to a /v1/ address, has the permission, and is still refused.
  • A request with an API token returns data from an affiliate other than the one the token was made in.