Documentation sections

Authentication

Every calculator call carries an API key, on every plan; a free key costs nothing. The calculator routes, the job routes and the usage endpoint take it in either header.

Keys start with rfc_. A key is shown once, when it is created, and never again: only its hash is stored.

Send the key

Send the key in the X-API-Key header, or as Authorization: Bearer rfc_…. A request with no key is refused with 401 and a keyUrl; a key that was never issued, or was revoked, is refused with 401 too. A 401 is never about the allowance: a spent allowance is 402 (see Errors).

The allowance belongs to the account

The calls of all an account's keys, revoked ones included, count against one monthly figure; it resets at the start of each calendar month in UTC, and every call is still attributed to the key that made it.

Monthly allowance and key limit per plan
Plan	Calls a month, and keys
Free	5 calls a month, 1 API key
Pro	100 calls a month, 3 API keys
API	10,000 calls a month, 5 API keys

Get a key

A person gets one from the dashboard. A program has two ways to hand its user one, and both give an ordinary rfc_ key, metered, listed and revocable like any other.

A key link

Open https://rftools.io/dashboard/?newKey=1&client=<clientId>[&label=<text>] in the user's browser. clientId names the program and matches ^[a-z0-9][a-z0-9-]{1,39}$, for example kicad-plugin; a value that does not match is ignored, not refused. A signed-out user signs in or signs up and comes back to the same link. The dashboard opens its create-key dialog with the label filled in (<clientId> — <date> unless the link gave one), and shows the key once for the user to paste into the program.

The dialog calls POST /api/py/v1/apikeys, which a signed-in session may call directly; the body is optional. An account at its key limit is refused with 400 and asked to revoke a key first.

Get a free API key

The device grant, for a program with no browser

The OAuth 2.0 device authorization grant (RFC 8628) gets a key to a program (a plugin, a CLI, a local MCP server) without the user pasting anything. The program asks for a code, shows the user the code and https://rftools.io/device/, and polls. The user signs in there, sees the name the program gave for itself, and approves or denies. On approval the program's next poll returns the key, once. Both endpoints take JSON or a form body.

A code is 8 letters from BCDFGHJKLMNPQRSTVWXZ, shown as XXXX-XXXX, and expires 10 minutes after it is issued.
Poll no faster than interval (5 s to start with).
The key counts toward the account's key limit; an account at its limit is asked to revoke a key first.
Show the user the code only. The device_code is the program's secret until it is exchanged.
The Python library does all of this: rftools login, or rftools.Client().login().

While waiting, the token endpoint answers 400 with an RFC 8628 error:

Device grant errors
error	What it means
authorization_pending	The user has not decided yet. Keep polling at the interval.
slow_down	Polled faster than the interval. The interval grows by 5 s; the body carries the new interval.
access_denied	The user denied the code, or the account reached its key limit before the key was collected. Stop polling.
expired_token	The code expired (10 minutes after it was issued) or its key was already collected. Start again.
invalid_grant	The device code was issued to another client_id.
invalid_request / unsupported_grant_type	A parameter is missing or the grant_type is wrong.

The device-grant endpoints are held to the no-credential rate limit, whatever they carry.

Either header

X-API-Key: rfc_a1b2c3d4e5f6…
# or
Authorization: Bearer rfc_a1b2c3d4e5f6…

Create a key from a signed-in session

curl -X POST https://rftools.io/api/py/v1/apikeys \
  -H "Authorization: Bearer $SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Bench PC",
    "client": "kicad-plugin"
  }'

import os

import httpx

response = httpx.post(
    "https://rftools.io/api/py/v1/apikeys",
    headers={"Authorization": f"Bearer {os.environ['SESSION_TOKEN']}"},
    json={"label": "Bench PC", "client": "kicad-plugin"},
)
print(response.status_code, response.json())

const response = await fetch("https://rftools.io/api/py/v1/apikeys", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SESSION_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "label": "Bench PC",
    "client": "kicad-plugin"
  }),
});
console.log(response.status, await response.json());

package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	body := []byte(`{
	  "label": "Bench PC",
	  "client": "kicad-plugin"
	}`)
	req, err := http.NewRequest("POST", "https://rftools.io/api/py/v1/apikeys", bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+os.Getenv("SESSION_TOKEN"))
	req.Header.Set("Content-Type", "application/json")
	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()
	out, _ := io.ReadAll(res.Body)
	fmt.Println(res.Status, string(out))
}

200application/json

{
  "key": "rfc_…",
  "key_id": "rfc_…",
  "created_at": 1758722711,
  "label": "Bench PC",
  "client": "kicad-plugin",
  "monthly_quota": 5
}

The key is in this response once, and never again.

The device grant

Device grant

# 1. the program asks for a code
curl -X POST https://rftools.io/api/py/v1/oauth/device/code \
  -H "Content-Type: application/json" \
  -d '{"client_id":"kicad-plugin"}'
# → {"device_code":"…","user_code":"BCDF-GHJK",
#    "verification_uri":"https://rftools.io/device/",
#    "verification_uri_complete":"https://rftools.io/device/?user_code=BCDF-GHJK",
#    "expires_in":600,"interval":5}

# 2. it shows the user the code and the address, then polls every interval seconds
curl -X POST https://rftools.io/api/py/v1/oauth/device/token \
  -H "Content-Type: application/json" \
  -d '{"grant_type":"urn:ietf:params:oauth:grant-type:device_code",
       "device_code":"…","client_id":"kicad-plugin"}'
# → 400 {"error":"authorization_pending", …}   until the user decides
# → 200 {"access_token":"rfc_…","token_type":"Bearer","key_id":"rfc_…",
#        "label":"kicad-plugin — 2026-09-24","client":"kicad-plugin","monthly_quota":5}