Abschnitte der Dokumentation

Authentifizierung

Jeder Rechneraufruf trägt einen API-Schlüssel, in jedem Tarif; ein kostenloser Schlüssel kostet nichts. Die Rechner-Routen, die Job-Routen und der Nutzungs-Endpunkt nehmen ihn in jedem der beiden Header an.

Schlüssel beginnen mit rfc_. Ein Schlüssel wird einmal angezeigt, wenn er erstellt wird, und nie wieder: Gespeichert wird nur sein Hash.

Den Schlüssel senden

Senden Sie den Schlüssel im Header X-API-Key oder als Authorization: Bearer rfc_…. Eine Anfrage ohne Schlüssel wird mit 401 und einer keyUrl abgelehnt; ein Schlüssel, der nie ausgegeben oder der widerrufen wurde, ebenfalls mit 401. Ein 401 betrifft nie das Kontingent: Ein verbrauchtes Kontingent ist 402 (siehe Fehler).

Das Kontingent gehört dem Konto

Die Aufrufe aller Schlüssel eines Kontos, widerrufene eingeschlossen, werden auf einen gemeinsamen Monatswert angerechnet; er wird zu Beginn jedes Kalendermonats in UTC zurückgesetzt, und jeder Aufruf wird weiterhin dem Schlüssel zugeordnet, der ihn ausgeführt hat.

Monatliches Kontingent und Schlüssellimit pro Tarif
Tarif	Aufrufe pro Monat und Schlüssel
Free	5 Aufrufe pro Monat, 1 API-Schlüssel
Pro	100 Aufrufe pro Monat, 3 API-Schlüssel
API	10.000 Aufrufe pro Monat, 5 API-Schlüssel

Einen Schlüssel holen

Eine Person holt sich einen im Dashboard. Ein Programm hat zwei Wege, seinem Nutzer einen zu verschaffen, und beide ergeben einen gewöhnlichen rfc_-Schlüssel, der gezählt, aufgelistet und widerrufen werden kann wie jeder andere.

Ein Schlüssel-Link

Öffnen Sie https://rftools.io/dashboard/?newKey=1&client=<clientId>[&label=<text>] im Browser des Nutzers. clientId benennt das Programm und entspricht ^[a-z0-9][a-z0-9-]{1,39}$, zum Beispiel kicad-plugin; ein Wert, der nicht passt, wird ignoriert, nicht abgelehnt. Ein abgemeldeter Nutzer meldet sich an oder registriert sich und kehrt zum selben Link zurück. Das Dashboard öffnet seinen Dialog zum Erstellen eines Schlüssels mit ausgefüllter Bezeichnung (<clientId> — <date>, sofern der Link keine angibt) und zeigt den Schlüssel einmal an, damit der Nutzer ihn in das Programm einfügt.

Der Dialog ruft POST /api/py/v1/apikeys auf, das eine angemeldete Sitzung auch direkt aufrufen darf; der Body ist optional. Ein Konto, das sein Schlüssellimit erreicht hat, wird mit 400 abgelehnt und gebeten, zuerst einen Schlüssel zu widerrufen.

Kostenlosen API-Schlüssel holen

Die Gerätefreigabe, für ein Programm ohne Browser

Die Gerätefreigabe nach OAuth 2.0 (Device Authorization Grant, RFC 8628) gibt einem Programm (einem Plugin, einer CLI, einem lokalen MCP-Server) einen Schlüssel, ohne dass der Nutzer etwas einfügt. Das Programm fordert einen Code an, zeigt dem Nutzer den Code und https://rftools.io/device/ und fragt dann regelmäßig ab. Der Nutzer meldet sich dort an, sieht den Namen, den das Programm sich selbst gegeben hat, und gibt frei oder lehnt ab. Nach der Freigabe liefert die nächste Abfrage des Programms den Schlüssel, ein einziges Mal. Beide Endpunkte nehmen JSON oder einen Formular-Body an.

Ein Code besteht aus 8 Buchstaben aus BCDFGHJKLMNPQRSTVWXZ, wird als XXXX-XXXX angezeigt und läuft 10 Minuten nach seiner Ausgabe ab.
Fragen Sie nicht schneller ab als interval (anfangs 5 s).
Der Schlüssel zählt zum Schlüssellimit des Kontos; ein Konto, das sein Limit erreicht hat, wird gebeten, zuerst einen Schlüssel zu widerrufen.
Zeigen Sie dem Nutzer nur den Code. Der device_code ist das Geheimnis des Programms, bis er eingetauscht ist.
Die Python-Bibliothek erledigt das alles: rftools login oder rftools.Client().login().

Während des Wartens antwortet der Token-Endpunkt mit 400 und einem RFC-8628-error:

Fehler der Gerätefreigabe
error	Bedeutung
authorization_pending	Der Nutzer hat noch nicht entschieden. Fragen Sie im Intervall weiter ab.
slow_down	Schneller abgefragt als im Intervall. Das Intervall wächst um 5 s; der Body trägt das neue Intervall.
access_denied	Der Nutzer hat den Code abgelehnt, oder das Konto hat sein Schlüssellimit erreicht, bevor der Schlüssel abgeholt wurde. Beenden Sie die Abfrage.
expired_token	Der Code ist abgelaufen (10 Minuten nach seiner Ausgabe), oder sein Schlüssel wurde bereits abgeholt. Beginnen Sie von vorn.
invalid_grant	Der Gerätecode wurde für eine andere client_id ausgegeben.
invalid_request / unsupported_grant_type	Ein Parameter fehlt, oder der grant_type ist falsch.

Die Endpunkte der Gerätefreigabe unterliegen dem Ratenlimit ohne Zugangsdaten, gleich was sie mitführen.

Einer der beiden Header

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

Einen Schlüssel aus einer angemeldeten Sitzung erstellen

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
}

Der Schlüssel steht einmal in dieser Antwort und nie wieder.

Die Gerätefreigabe

Gerätefreigabe

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