Your first API call

By the end of this page you will hold a personal access token and have made an authenticated request. You need a Falcata account and a terminal.

1. Get a token

Tokens are minted through the device authorization flow: you request a short code over HTTP, approve it in your browser at id.falcata.io, and receive a personal access token (fpat_…). The full walkthrough with exact request and response shapes is on Device authorization — it is three curl commands.

If you have the furnace CLI, furnace auth login drives the same flow and stores the token for you.

2. Call the API

curl https://api.falcata.io/api/v1/auth/whoami \
  -H "Authorization: Bearer $FURNACE_TOKEN"

A successful response identifies your user and the token's effective scope. A 401 means the token is missing, expired, or revoked — the WWW-Authenticate header points at the OAuth discovery documents.

3. Read something real

List your tasks:

curl "https://api.falcata.io/api/v1/tasks" \
  -H "Authorization: Bearer $FURNACE_TOKEN"

What to know before writing

• Rate limits: 600 requests/minute per token, burst 100. Watch the RateLimit response headers; on 429, honor Retry-After.
• Idempotency: write endpoints accept an Idempotency-Key header; retries within 24 hours replay the original result.
• Errors are structured JSON with a machine-readable code.

Full protocol details: REST API. Every operation: the generated reference. When something fails: Troubleshooting.