Authentication / API keys

GetRatesAPI uses two independent, header-only credential schemes. No cookie or query-string credential is accepted anywhere.

A session token is never accepted on the rate-serving endpoint or by any MCP tool; an API key is never accepted on account-management endpoints.

1. Register

curl -X POST https://your-getratesapi-host/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"a-strong-password"}'

await fetch("https://your-getratesapi-host/v1/auth/register", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ email: "you@example.com", password: "a-strong-password" }),
});

2. Log in

curl -X POST https://your-getratesapi-host/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"you@example.com","password":"a-strong-password"}'

Success 200:

{
  "session_token": "gra_sess_0000000000000000000000000000000000000000000",
  "expires_at": "2026-10-09T12:00:00Z"
}

The session token has a fixed 24-hour expiration. There is no refresh endpoint — log in again once it expires.

3. Create an API key

Using the session token from step 2:

curl -X POST https://your-getratesapi-host/v1/account/api-keys \
  -H "Authorization: Session gra_sess_0000000000000000000000000000000000000000000" \
  -H "Content-Type: application/json" \
  -d '{"name":"my first key"}'

await fetch("https://your-getratesapi-host/v1/account/api-keys", {
  method: "POST",
  headers: {
    Authorization: "Session gra_sess_0000000000000000000000000000000000000000000",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "my first key" }),
});

Success 201:

{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "name": "my first key",
  "key_prefix": "gra_live_00000000",
  "created_at": "2026-10-08T12:00:00Z",
  "api_key": "gra_live_0000000000000000000000000000000000000000000000000000000000000000"
}

api_key is returned exactly once in this response and is never retrievable again — store it securely immediately. The key format is gra_live_ followed by 64 lowercase hex characters.

key_prefix is a 17-character value: the gra_live_ prefix plus the first 8 hexadecimal characters of the key’s own secret portion — it is derived from the secret, not a shared constant. It is included so you can visually distinguish keys in a list; it never reveals enough of the secret to reconstruct or guess the full key.

4. Use the API key

curl https://your-getratesapi-host/v1/rates/EUR/USD \
  -H "Authorization: ApiKey gra_live_0000000000000000000000000000000000000000000000000000000000000000"

Use the same Authorization: ApiKey <key> header for every hosted MCP tool call.

Managing API keys

• GET /v1/account/api-keys (Session required) — lists all keys for your account, including revoked ones. Secrets are never included in list output — only id, name, key_prefix, created_at.
• DELETE /v1/account/api-keys/{id} (Session required) — revokes a key. 204 on success. Unknown, foreign, or already-revoked ids return 404 not_found.

curl -X DELETE https://your-getratesapi-host/v1/account/api-keys/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  -H "Authorization: Session gra_sess_0000000000000000000000000000000000000000000"

Known gaps

There is currently no password-change endpoint and no team/multi-account selector. Email/password verification uses a real token-based flow, but there is no external email delivery configured outside the backend’s own test harness in this milestone — expect delivery accordingly in a local development environment.