# Falcata API authentication

## Discover

Read the [RFC 9728 protected resource metadata](https://api.falcata.io/.well-known/oauth-protected-resource) and the [RFC 8414 authorization server metadata](https://api.falcata.io/.well-known/oauth-authorization-server) before starting an OAuth flow. The API includes a WWW-Authenticate challenge with 401 responses.

## Pick a method

Use a Personal Access Token beginning with `fpat_` for an existing machine credential. Use the device flow for a CLI or other input-constrained client. Use the authorization-code flow with PKCE for a client that can receive a browser redirect; its authorization, token, registration, and supported grant details come from the authorization server metadata.

## Register

Authorization-code clients register by sending their client metadata to [the dynamic registration endpoint](https://api.falcata.io/oauth/register). Device-flow clients do not register before requesting a device code.

## Claim

For the device flow, POST to [the device authorization endpoint](https://api.falcata.io/api/v1/auth/device/code), show the returned verification URI and user code to the user, then poll [the device token endpoint](https://api.falcata.io/api/v1/auth/device/token) at the returned interval. For the authorization-code flow, begin at [the authorization endpoint](https://api.falcata.io/oauth/authorize) and exchange the returned code at [the OAuth token endpoint](https://api.falcata.io/oauth/token) using PKCE.

## Use the credential

Send the resulting `fpat_` credential as `Authorization: Bearer <token>` to the [Falcata REST API](https://api.falcata.io/api/v1) or [MCP endpoint](https://api.falcata.io/mcp). MCP initialize and tools/list are public; tools/call requires the Bearer credential.

## Errors

On a 401 response, read WWW-Authenticate and obtain or replace the credential before retrying. During the device flow, keep polling only while the token endpoint returns `authorization_pending`; stop on `access_denied` or `expired_token`. Treat 403 as an authenticated caller lacking the required Furnace permission.

## Revocation

Revoke the currently used Personal Access Token by sending an authenticated DELETE request to [the token endpoint](https://api.falcata.io/api/v1/auth/token). Falcata does not advertise a separate OAuth revocation endpoint.