Seções da documentação

Autenticação

Toda chamada a uma calculadora leva uma chave de API, em qualquer plano; uma chave gratuita não custa nada. As rotas das calculadoras, as rotas dos trabalhos e o endpoint de uso aceitam a chave em qualquer um dos dois cabeçalhos.

As chaves começam com rfc_. Uma chave é mostrada uma vez, quando é criada, e nunca mais: só o hash dela é guardado.

Enviar a chave

Envie a chave no cabeçalho X-API-Key ou como Authorization: Bearer rfc_…. Uma requisição sem chave é recusada com 401 e uma keyUrl; uma chave que nunca foi emitida, ou que foi revogada, também é recusada com 401. Um 401 nunca diz respeito à cota: uma cota esgotada é 402 (veja Erros).

A cota pertence à conta

As chamadas de todas as chaves de uma conta, incluindo as revogadas, contam para um único total mensal; ele é zerado no início de cada mês do calendário em UTC, e cada chamada continua atribuída à chave que a fez.

Cota mensal e limite de chaves por plano
Plano	Chamadas por mês, e chaves
Free	5 chamadas por mês, 1 chave de API
Pro	100 chamadas por mês, 3 chaves de API
API	10.000 chamadas por mês, 5 chaves de API

Obter uma chave

Uma pessoa obtém a sua no painel. Um programa tem duas maneiras de entregar uma ao seu usuário, e ambas dão uma chave rfc_ comum, contabilizada, listada e revogável como qualquer outra.

Um link de chave

Abra https://rftools.io/dashboard/?newKey=1&client=<clientId>[&label=<text>] no navegador do usuário. clientId nomeia o programa e deve corresponder a ^[a-z0-9][a-z0-9-]{1,39}$, por exemplo kicad-plugin; um valor que não corresponde é ignorado, não recusado. Um usuário desconectado entra ou se cadastra e volta ao mesmo link. O painel abre a caixa de diálogo de criação de chave com o rótulo preenchido (<clientId> — <date>, a menos que o link informe outro) e mostra a chave uma vez para o usuário colá-la no programa.

A caixa de diálogo chama POST /api/py/v1/apikeys, que uma sessão conectada pode chamar diretamente; o corpo é opcional. Uma conta no limite de chaves é recusada com 400 e orientada a revogar uma chave antes.

Obter uma chave de API gratuita

A autorização de dispositivo, para um programa sem navegador

A concessão de autorização de dispositivo do OAuth 2.0 (RFC 8628) entrega uma chave a um programa (um plugin, uma CLI, um servidor MCP local) sem que o usuário cole nada. O programa pede um código, mostra ao usuário o código e https://rftools.io/device/ e consulta periodicamente. O usuário entra lá, vê o nome que o programa deu a si mesmo e aprova ou nega. Após a aprovação, a próxima consulta do programa devolve a chave, uma única vez. Os dois endpoints aceitam JSON ou um corpo de formulário.

Um código tem 8 letras de BCDFGHJKLMNPQRSTVWXZ, aparece como XXXX-XXXX e expira 10 minutos depois de emitido.
Não consulte mais rápido que interval (5 s no início).
A chave conta no limite de chaves da conta; uma conta no limite é orientada a revogar uma chave antes.
Mostre ao usuário apenas o código. O device_code é o segredo do programa até ser trocado.
A biblioteca Python faz tudo isso: rftools login ou rftools.Client().login().

Enquanto espera, o endpoint de token responde 400 com um error da RFC 8628:

Erros da autorização de dispositivo
error	O que significa
authorization_pending	O usuário ainda não decidiu. Continue consultando no intervalo.
slow_down	Consultou mais rápido que o intervalo. O intervalo aumenta 5 s; o corpo traz o novo intervalo.
access_denied	O usuário negou o código, ou a conta atingiu o limite de chaves antes de a chave ser buscada. Pare de consultar.
expired_token	O código expirou (10 minutos depois de emitido) ou a chave dele já foi buscada. Comece de novo.
invalid_grant	O código de dispositivo foi emitido para outro client_id.
invalid_request / unsupported_grant_type	Falta um parâmetro ou o grant_type está errado.

Os endpoints da autorização de dispositivo seguem o limite de taxa sem credencial, não importa o que levem.

Qualquer um dos cabeçalhos

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

Criar uma chave a partir de uma sessão conectada

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
}

A chave aparece nesta resposta uma única vez, e nunca mais.

A autorização de dispositivo

Autorização de dispositivo

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