Sections de la documentation

Authentification

Chaque appel à un calculateur porte une clé d'API, quelle que soit l'offre ; une clé gratuite ne coûte rien. Les routes des calculateurs, celles des tâches et le point de terminaison d'usage l'acceptent dans l'un ou l'autre en-tête.

Les clés commencent par rfc_. Une clé est affichée une seule fois, à sa création, puis plus jamais : seul son hachage est conservé.

Envoyer la clé

Envoyez la clé dans l'en-tête X-API-Key ou sous la forme Authorization: Bearer rfc_…. Une requête sans clé est refusée avec 401 et une keyUrl ; une clé qui n'a jamais été émise, ou qui a été révoquée, est également refusée avec 401. Un 401 ne concerne jamais le quota : un quota épuisé, c'est 402 (voir Erreurs).

Le quota appartient au compte

Les appels de toutes les clés d'un compte, y compris les clés révoquées, sont décomptés d'un seul chiffre mensuel ; il est réinitialisé au début de chaque mois civil en UTC, et chaque appel reste attribué à la clé qui l'a fait.

Quota mensuel et limite de clés par offre
Offre	Appels par mois, et clés
Free	5 appels par mois, 1 clé d'API
Pro	100 appels par mois, 3 clés d'API
API	10 000 appels par mois, 5 clés d'API

Obtenir une clé

Une personne en obtient une sur le tableau de bord. Un programme dispose de deux moyens d'en fournir une à son utilisateur, et tous deux donnent une clé rfc_ ordinaire, décomptée, listée et révocable comme toute autre.

Un lien de clé

Ouvrez https://rftools.io/dashboard/?newKey=1&client=<clientId>[&label=<text>] dans le navigateur de l'utilisateur. clientId nomme le programme et respecte ^[a-z0-9][a-z0-9-]{1,39}$, par exemple kicad-plugin ; une valeur non conforme est ignorée, pas refusée. Un utilisateur déconnecté se connecte ou s'inscrit, puis revient au même lien. Le tableau de bord ouvre sa boîte de dialogue de création de clé avec le libellé prérempli (<clientId> — <date> si le lien n'en donne pas) et affiche la clé une fois pour que l'utilisateur la colle dans le programme.

La boîte de dialogue appelle POST /api/py/v1/apikeys, qu'une session connectée peut aussi appeler directement ; le corps est facultatif. Un compte qui a atteint sa limite de clés est refusé avec 400 et invité à révoquer d'abord une clé.

Obtenir une clé d'API gratuite

L'autorisation d'appareil, pour un programme sans navigateur

L'autorisation d'appareil OAuth 2.0 (RFC 8628) remet une clé à un programme (une extension, une CLI, un serveur MCP local) sans que l'utilisateur ait rien à coller. Le programme demande un code, montre à l'utilisateur le code et https://rftools.io/device/, puis interroge à intervalles réguliers. L'utilisateur s'y connecte, voit le nom que le programme s'est donné, et approuve ou refuse. Après l'approbation, l'interrogation suivante du programme renvoie la clé, une seule fois. Les deux points de terminaison acceptent du JSON ou un corps de formulaire.

Un code compte 8 lettres tirées de BCDFGHJKLMNPQRSTVWXZ, s'affiche sous la forme XXXX-XXXX et expire 10 minutes après son émission.
N'interrogez pas plus vite que interval (5 s au départ).
La clé compte dans la limite de clés du compte ; un compte qui a atteint sa limite est invité à révoquer d'abord une clé.
Ne montrez à l'utilisateur que le code. Le device_code est le secret du programme jusqu'à son échange.
La bibliothèque Python fait tout cela : rftools login ou rftools.Client().login().

Pendant l'attente, le point de terminaison du jeton répond 400 avec une error RFC 8628 :

Erreurs de l'autorisation d'appareil
error	Signification
authorization_pending	L'utilisateur n'a pas encore décidé. Continuez à interroger à l'intervalle prévu.
slow_down	Interrogation plus rapide que l'intervalle. L'intervalle augmente de 5 s ; le corps porte le nouvel intervalle.
access_denied	L'utilisateur a refusé le code, ou le compte a atteint sa limite de clés avant la récupération de la clé. Cessez d'interroger.
expired_token	Le code a expiré (10 minutes après son émission) ou sa clé a déjà été récupérée. Recommencez.
invalid_grant	Le code d'appareil a été émis pour un autre client_id.
invalid_request / unsupported_grant_type	Un paramètre manque ou le grant_type est incorrect.

Les points de terminaison de l'autorisation d'appareil sont soumis à la limite de débit sans identifiant, quoi qu'ils portent.

L'un ou l'autre en-tête

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

Créer une clé depuis une session connectée

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
}

La clé figure une seule fois dans cette réponse, et plus jamais ensuite.

L'autorisation d'appareil

Autorisation d'appareil

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