Get started
Authentication & scopes
API keys for software and agents, sessions for people in the dashboard, and what each scope allows.
Every /v1 endpoint needs credentials except signup, login, the payment webhook and the health check. There are two kinds:
| Who | How |
|---|---|
| Software and AI agents | An API key in the Authorization header: Authorization: Bearer 1fly_test_… |
| People in the dashboard | The onefly_session cookie, set by POST /v1/auth/login or POST /v1/auth/signup |
A request that has neither, or a bad one, gets 401 UNAUTHENTICATED.
API keys#
GET /v1/orders HTTP/1.1
Host: localhost:4000
Authorization: Bearer 1fly_test_0123456789abcdef0123456789abcdef01234567- Format.
1fly_test_or1fly_live_followed by 40 hex characters. Anything else is rejected before lookup with401 UNAUTHENTICATED(“Malformed API key”). - Mode. Test keys create test orders against mock suppliers. Live keys exist for the Basic and Pro plans but cannot create orders yet (
403 LIVE_MODE_UNAVAILABLE). - Account. A key belongs to one account. It sees only that account’s orders, analytics and logs. The account comes from the key, never from the request body.
- Shown once. The full secret is displayed only when the key is created. Afterwards the dashboard shows the prefix (for example
1fly_test_a1b2), the scopes, when it was created, last used (updated at most once a minute) and when it expires. - Expiry. 30, 90 or 365 days, or never. An expired key gets
401 UNAUTHENTICATEDwith the expiry date in the message.
Create keys at http://localhost:3000/app/api-keys. Owners, admins and developers can create and revoke keys; viewers cannot. Key management is dashboard-only: an API key cannot create or revoke keys (403 FORBIDDEN).
Warning
Treat a key like a password. Keep it in a secret manager or environment variable, never in client-side code, a mobile app or a git repository. 1fly never stores the secret in request logs.
Scopes#
Each key carries one or more scopes. A request whose key lacks the scope gets 403 FORBIDDEN naming the missing scope. Give each key only what its job needs.
| Scope | Allows | Endpoints |
|---|---|---|
orders:read | Read orders, their status and full timeline. | GET /v1/ordersGET /v1/orders/{id}GET /v1/orders/{id}/timeline |
orders:write | Create orders, confirm price changes, cancel, and run test simulations. | POST /v1/ordersPOST /v1/orders/{id}/price-decisionPOST /v1/orders/{id}/cancelPOST /v1/orders/{id}/simulate-paymentPOST /v1/dev/simulate |
orders:issue | Issue tickets for orders booked with issue "manual", and void issued tickets. | POST /v1/orders/{id}/issuePOST /v1/orders/{id}/void |
search:read | Find airports, search flights and read offers, fare options and fare rules. Implied by orders:write. | GET /v1/airportsPOST /v1/searchesGET /v1/searches/{id}GET /v1/offers/{id}GET /v1/offers/{id}/fare-optionsGET /v1/offers/{id}/rules |
analytics:read | Read booking analytics: funnel, step health, errors. | GET /v1/analytics/* |
logs:read | Read this account’s API request logs. | GET /v1/logsGET /v1/logs/{id} |
POST /v1/webhooks/mockpay needs no key: the payment provider calls it.
Roles in the dashboard#
People act through the dashboard with the scopes of their role in the account:
| Role | Scopes in the dashboard | Can create API keys |
|---|---|---|
owner | orders:readorders:writeorders:issuesearch:readanalytics:readlogs:read | Yes |
admin | orders:readorders:writeorders:issuesearch:readanalytics:readlogs:read | Yes |
developer | orders:readorders:writeorders:issuesearch:readanalytics:readlogs:read | Yes |
viewer | orders:readsearch:readanalytics:readlogs:read | No |
Rotating a key#
Rotate on a schedule and immediately if a key may have leaked:
- Create a new key with the same scopes.
- Deploy it alongside the old one and switch traffic to it.
- Check the old key’s Last used in the dashboard, or filter the request log by its
keyId, until it stops changing. - Revoke the old key.
Revocation takes effect on the next request: the key gets 401 UNAUTHENTICATED (“API key … was revoked”). It cannot be undone; create a new key instead.
Sessions (dashboard)#
The dashboard signs people in with POST /v1/auth/login ({ email, password }), which sets an httpOnly, SameSite=Lax cookie named onefly_session. Browsers must send it with credentials: 'include'; CORS allows credentials from the dashboard origin only. A person who belongs to several accounts switches with POST /v1/auth/switch-account. Repeated failed logins are temporarily blocked with 429 RATE_LIMITED.
Use sessions for people and API keys for software. Do not script the login endpoint to drive the API from a server.
Optional headers#
Our own MCP server adds x-1fly-channel: mcp and x-1fly-mcp-tool: <tool name> to every call so the request log can show which agent tool made it. If you build your own agent integration, you may send them too.