# auth.md

## Agent authentication for FlightLabs

FlightLabs supports two credential styles for AI agents:

1. **API key** (`access_key`) — fastest path for humans and agents
2. **OAuth 2.0** (authorization code) — for platforms that connect without pasting keys

Billing and subscription are **not** created by OAuth alone. A human (or org) must register and start a trial / paid plan; OAuth then grants the agent a token bound to that account.

### Account tiers

| Account | API key in dashboard | OAuth for agents | Notes |
|---|---|---|---|
| Free (registered, no sub) | No | Blocked | Dashboard try-out only (~50 calls/mo) |
| Free trial | Yes | Allowed | Same quota as API key |
| Paid | Yes | Allowed | Plan quota (+ Soft Limit if enabled) |

OAuth authorize redirects free users to `/oauth/agent-connect`. Tokens issued without trial/paid are revoked. Bearer mapping only works for trial/paid.

---

## Path A — API key

1. Register: https://www.goflightlabs.com/register (free trial available)
2. Copy your `access_key` from the dashboard
3. Call the API with a header (preferred) or query param:

```http
GET https://www.goflightlabs.com/flights?flightIata=AA217
Authorization: Bearer YOUR_KEY
```

Query `?access_key=` still works on the REST API. **Do not** put the key on the MCP URL — Claude Desktop and claude.ai strip query tokens.

MCP:

```
https://mcp.goflightlabs.com/mcp
Authorization: Bearer YOUR_KEY
```

---

## Path B — OAuth 2.0 for agents

Discovery:

- Authorization Server: https://www.goflightlabs.com/.well-known/oauth-authorization-server
- OpenID config: https://www.goflightlabs.com/.well-known/openid-configuration
- Protected Resource: https://www.goflightlabs.com/.well-known/oauth-protected-resource
- Human connect guide: https://www.goflightlabs.com/oauth/agent-connect
- A2A agent card: https://www.goflightlabs.com/.well-known/agent-card.json

### Flow

1. **Subscribe / register** (human): https://www.goflightlabs.com/register  
   Creates the account, trial/plan, and API quota.
2. **Register OAuth client** (platform): create a Passport client in the FlightLabs dashboard/ops, or contact support for a public agent client. Redirect URI must be allowlisted.
3. **Authorize**: send the user to  
   `GET /oauth/authorize?client_id=...&redirect_uri=...&response_type=code&scope=flightlabs.api&state=...`  
   User logs in (or registers) and approves.
4. **Token**: `POST /oauth/token` with `grant_type=authorization_code` (+ PKCE if public client).
5. **Call API** with `Authorization: Bearer <access_token>`.  
   The token is mapped to the same user quota as `access_key`.

### Scopes

| Scope | Meaning |
|---|---|
| `flightlabs.api` | Call FlightLabs flight data endpoints under the authenticated account |

### Important

- OAuth does **not** auto-subscribe the agent to a paid plan.
- Without a registered/trial user behind the token, API calls will fail like a missing key.
- Prefer OAuth for Claude, Cursor, and ChatGPT connectors. Use an API key as `Authorization: Bearer` for scripts. Do not put tokens in the MCP query string.

---

## Support

- Docs: https://www.goflightlabs.com/documentation
- MCP: https://www.goflightlabs.com/mcp
- Terms: https://www.goflightlabs.com/terms