# Authentication

> How API keys work: creating one, sending it, rotating it, and what happens when one leaks. Keys are shown once and hashed at rest.

Canonical page: https://www.refolk.ai/developers/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

**curl**

```bash
curl https://www.refolk.ai/api/v1/credits \
  -H "Authorization: Bearer $REFOLK_API_KEY"
```

**Header only**

```text
Authorization: Bearer rfk_live_...
```

**Alternative**

```text
X-Api-Key: rfk_live_...
```

`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](/developers/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](/hire/api). An
account may hold 10 live keys at once, which is enough for
one per integration and few enough that the list stays readable.

| Property | Behaviour |
| --- | --- |
| Visibility | Shown once, at creation. Only a hash is stored. |
| Prefix | `rfk_live_`, so a leaked key is recognisable as one. |
| Revocation | Immediate, on the next request. |
| Blast radius | One key. Revoking does not touch the others or sign you out. |
| Last used | Stamped on every call, so a stale key is visible in the list. |

## 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.

> **Why there is no expiry**
>
> A key that expires on a schedule fails at the worst possible moment, which is
> whenever nobody is looking. Rotation is better done deliberately, and the
> last-used column is what tells you it is safe to finish.

## 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](mailto:hello@refolk.ai).



---

## More of the API documentation

- [Quickstart](https://www.refolk.ai/developers/quickstart.md): Create a key, run your first search, and read what comes back. A working request in under two minutes, in curl, TypeScript, and Python.
- [Credits and limits](https://www.refolk.ai/developers/credits-and-limits.md): What each call costs, how a search is reserved and reconciled, what the rate limits are, and how to check a balance before a long run.
- [Playground](https://www.refolk.ai/developers/playground.md): Run any endpoint from the browser, signed in, on your own credits. Prefilled examples, the real response, and the equivalent curl for your own code.
- [Search in plain English](https://www.refolk.ai/developers/agentic-search.md): POST /v1/search. One sentence in, a ranked shortlist out, with the evidence behind every pick. Blocking or streamed as server-sent events.
- [Search with filters](https://www.refolk.ai/developers/structured-search.md): POST /v1/people/search. An exact filter set in, a deterministic page of people out, one credit a call. Every field, every allowed value, and how to paginate.
- [Errors](https://www.refolk.ai/developers/errors.md): One error shape for every endpoint, a closed set of types, and which of them are worth retrying. What gets refunded when a call fails.
- [MCP server](https://www.refolk.ai/developers/mcp.md): Give Claude, Cursor, VS Code, or any MCP client the ability to search for people mid-conversation. One URL, one header, four tools.
- [OpenAPI document](https://www.refolk.ai/api/v1/openapi.json): the machine-readable specification.

Authenticate with `Authorization: Bearer rfk_live_...`. Keys are created at https://www.refolk.ai/hire/api.