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#

HTTP
GET /v1/orders HTTP/1.1
Host: localhost:4000
Authorization: Bearer 1fly_test_0123456789abcdef0123456789abcdef01234567
  • Format. 1fly_test_ or 1fly_live_ followed by 40 hex characters. Anything else is rejected before lookup with 401 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 UNAUTHENTICATED with 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.

ScopeAllowsEndpoints
orders:readRead orders, their status and full timeline.GET /v1/ordersGET /v1/orders/{id}GET /v1/orders/{id}/timeline
orders:writeCreate 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:issueIssue tickets for orders booked with issue "manual", and void issued tickets.POST /v1/orders/{id}/issuePOST /v1/orders/{id}/void
search:readFind 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:readRead booking analytics: funnel, step health, errors.GET /v1/analytics/*
logs:readRead 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:

RoleScopes in the dashboardCan create API keys
ownerorders:readorders:writeorders:issuesearch:readanalytics:readlogs:readYes
adminorders:readorders:writeorders:issuesearch:readanalytics:readlogs:readYes
developerorders:readorders:writeorders:issuesearch:readanalytics:readlogs:readYes
viewerorders:readsearch:readanalytics:readlogs:readNo

Rotating a key#

Rotate on a schedule and immediately if a key may have leaked:

  1. Create a new key with the same scopes.
  2. Deploy it alongside the old one and switch traffic to it.
  3. Check the old key’s Last used in the dashboard, or filter the request log by its keyId, until it stops changing.
  4. 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.

API version v0.0.1 · Spec generated from source on 2026-11-22Changelog · Prices in so‘m (UZS)