# FlightQueue auth.md

How an AI agent registers with FlightQueue and authenticates. Everything below
works today, without a human in the loop.

- Registration endpoint: `POST https://flightqueue.com/api/agent/register`
- API base: `https://flightqueue.com/api/v1`
- MCP endpoint: `https://mcp.flightqueue.com/mcp`
- Authorization server (MCP): `https://mcp.flightqueue.com`
- Protected resource metadata: `https://flightqueue.com/.well-known/oauth-protected-resource`

## Pick a method

| You are | Use |
|---|---|
| An MCP client (Claude, Cursor, Claude Code, ChatGPT) | OAuth 2.1 at `https://mcp.flightqueue.com` |
| A script, crawler, or custom agent | Anonymous registration, below |
| A human | https://flightqueue.com/signup |

## Anonymous registration (no human, no payment)

```http
POST /api/agent/register HTTP/1.1
Host: flightqueue.com
Content-Type: application/json

{"agent_name": "my-agent", "contact_email": "ops@example.com"}
```

Both fields are optional. `contact_email` is only used to reach the operator
about abuse or deprecation; it is never required and never verified.

`201 Created`:

```json
{
  "success": true,
  "agent_id": "…",
  "api_key": "fqagent_…",
  "tier": "free"
}
```

The key is returned **once** and is not recoverable. Each registration creates
its own isolated account, so a key can never be scoped to another user's data.

Rate limits are per source IP — a per-minute burst cap and a per-day cap. Both
return `429` with `"error": "rate_limited"`. Back off; do not rotate IPs.

## Using the key

```http
GET /api/v1/airports/JFK/delays HTTP/1.1
Host: flightqueue.com
Authorization: Bearer fqagent_…
```

`X-API-Key: fqagent_…` is accepted as an equivalent. Send one, not both.

Paid developer keys use the `fq_live_` prefix and are issued from the
dashboard after purchase, not from this endpoint.

Inspect a key's account, tier and usage at any time:

```http
GET /api/agent/me HTTP/1.1
Authorization: Bearer fqagent_…
```

## OAuth 2.1 (MCP clients)

`https://mcp.flightqueue.com` is a full authorization server with Dynamic Client
Registration — no pre-shared client ID needed.

- Metadata: `https://mcp.flightqueue.com/.well-known/oauth-authorization-server`
  (`https://flightqueue.com/.well-known/oauth-authorization-server` redirects here)
- Client registration: `https://mcp.flightqueue.com/register` (RFC 7591)
- Authorization code + PKCE `S256` only. Scope: `read`.
- The user approves the connection at `https://flightqueue.com/connect-mcp`.

Most MCP clients do all of this automatically. Adding the server URL is enough:

```
claude mcp add --transport http flightqueue https://mcp.flightqueue.com/mcp
```

## Errors

| Status | Meaning | Do |
|---|---|---|
| `401 INVALID_API_KEY` | Missing, malformed, or revoked key | Re-register or re-auth |
| `403 PREMIUM_REQUIRED` | Valid key, tier too low | Stop. Surface https://flightqueue.com/pricing |
| `429 rate_limited` | Per-IP or per-key limit | Back off exponentially |

`403` is never retryable. Retrying it is the fastest way to get blocked.

## What a free key unlocks

- `search_airports` — search 8,000+ airports by name, city, IATA, or ICAO
- `get_airport_overview` — location, terminals, runways, current delays
- `compare_airports` — side-by-side wait/delay comparison
- `get_faa_delays` — current US FAA delays, ground stops, weather impacts
- `get_airport_delays_summary` — FAA delay status for one airport
- `get_security_wait_estimate` — current TSA security wait snapshot
- `get_best_time_to_fly` — recommended arrival window for a flight time
- `get_crowd_reports` — recent user-submitted wait reports
- `get_airline_baggage_rankings` — airlines ranked by mishandled-bag rate
- `get_airline_baggage_policy` — carry-on/checked policy for an airline
- `get_ees_wait_times` — EU Entry/Exit System border waits across Schengen airports
- `get_ees_forecast` — 24h EES border forecast for one airport, entry vs exit
- `check_schengen_days` — Schengen 90/180 allowance and overstay projection
- `get_aviation_weather` — METAR, TAF, and flight category for an airport
- `get_lounges` — lounges by terminal with access rules and amenities
- `get_terminals` — terminals, their airlines, and checkpoints
- `submit_wait_time_report` — report an observed wait time; feeds the shared prediction model
- `create_wait_time_alert` — alert when security wait crosses a threshold (mobile push only)
- `discover_more_flight_tools` — other FlightQueue MCP servers worth connecting

Paid only:

- `get_wait_time_predictions` — 24h / 7-day security-wait forecasts
- `get_historical_wait_times` — 7-day / 90-day hourly history
- `get_live_wait_time` — real-time scrape from 69+ airports

## Revocation

`DELETE /api/keys/{keyId}`, or from the dashboard. A revoked key returns
`401` on the next call; there is no grace period. Treat a sudden `401` on a
previously working key as revocation, not as a transient error.

## More

- Quickstart: https://flightqueue.com/features/agent-access
- OpenAPI 3.1: https://flightqueue.com/openapi.json
- Skills: https://flightqueue.com/.well-known/agent-skills/index.json
- Machine-readable index: https://flightqueue.com/llms.txt