Authentication

One credential: an API key, sent as a bearer token on every request. There is no OAuth dance, no signing, and no session. A key is minted on purpose, carried on purpose, and revoked on its own.

Sending a key#

X-Api-Key is accepted as well, with the bare key as its value. It exists because a fair number of HTTP clients and MCP configurations only give you a plain header field to fill in, and refusing that spelling buys nothing.

Why not a session cookie#

Session cookies are deliberately not accepted on the API. A cookie is authority your browser attaches on its own, to any request that happens to be aimed at this domain, whether or not you asked for it. That is fine for a page you are looking at and wrong for an endpoint reachable from anywhere. A key is only ever sent because something chose to send it.

The same reasoning is why the playground has nowhere to paste a key: it runs on your session and prints the curl you would run with your key, rather than teaching you to put a live credential into a text box in a web page.

Creating, listing, and revoking#

All three live on the API page. An account may hold 10 live keys at once, which is enough for one per integration and few enough that the list stays readable.

Rotating a key#

Create the new one first, deploy it, confirm the traffic has moved by watching the last-used timestamps in settings, then revoke the old one. Doing it in that order means there is never a moment when the integration has no working credential.

If a key leaks#

Revoke it. That is the whole procedure, and it is immediate.

Keys carry the rfk_live_ prefix so a key pasted into a public repository, a log line, or a support ticket is recognisable as one at a glance, by a person and by the secret scanners that watch public code. If you think a key has been used by someone else, check the balance and write to hello@refolk.ai.