A scope is a permission token your integration asks the user (or themselves, for server-to-server) to grant. Each access token carries the list of granted scopes; each endpoint requires one.
Request multiple scopes by joining them with a single space:
scope=flights:read flights:write profile:read
Catalog
| Scope | What it grants | Status |
|---|---|---|
flights:read | List a user's flights; read scoring, metadata, summarised analysis; download the raw IGC file | Stable |
flights:write | Upload IGC files to the user's logbook | Stable |
profile:read | Read display name, club, CIVL id, public-profile flag | Stable |
profile:email | Read the account email address (in addition to profile:read) | Stable |
profile:write | Update display name, club affiliation, license info, and safety contacts | Stable, write |
community:read | Read public community data (takeoff sites, leaderboards, thermal hotspots, the screen gallery) | Stable |
tasks:read | Read the pilot's competition tasks, waypoint collections and planned routes, also as .wpt / .cup / .gpx files; browse the shared task library | Stable |
tasks:write | Save competition tasks, waypoint collections and planned routes to the pilot's account | Stable, write |
screens:read | Read the pilot's instrument screen layouts | Stable |
screens:write | Create, update, delete and publish the pilot's screen layouts | Stable, write |
airspace:read | Read airspace region descriptors, temporary activations and the OpenAir files the pilot saved in the XC planner | Stable |
live:write | Publish live positions, mint share links, and raise take-off / landing / emergency notifications | Stable, write |
Restrictions
-
Pending applications can only obtain read-only scopes (
flights:read,profile:read,profile:email,community:read,tasks:read,screens:read,airspace:read), and only for their own owner. Every write scope above therefore needs the application approved before it can be exercised even once. Once an admin promotes the app toapproved, it can request its write scopes from any pilot. -
No scope deletes flights. A pilot's logbook is only ever deleted by the pilot, on we-fly itself. Apps learn about it from the
flight.deletedwebhook or the tombstones in a?sincedelta, and mirror it. -
Public clients (SPAs, mobile apps with no server-side secret) must use PKCE and cannot use
client_credentials. They CAN request any scope via Authorization Code, subject to user consent.
Notes on the newer scopes
tasks:* covers waypoints too. A competition task and a waypoint
collection are the same thing to a pilot (the set of places this flight is
about), and an integration that imports one almost always wants the other.
Splitting them would have produced a consent screen with two lines that nobody
could tell apart.
screens:*, not cockpits:*. The resource is a flight-instrument screen
layout. we-fly's own /cockpit pages are its statistics dashboard, an
unrelated feature that already owns that word. See
the instrument guide.
live:write covers notifications as well as positions. From the pilot's
point of view they are one act: telling we-fly where they are so that somebody
else can be told. A separate notify:write would have asked them to reason
about a distinction that only exists in our routing table.
Airspace activations are read with airspace:read but delivered per pilot.
The scope gets you the endpoint; the data additionally requires the pilot to
have connected their own autorouter account, because the underlying NOTAM
source may not be redistributed under a shared one. A pilot without that
connection gets 200 with an empty list and source.available: false, never
a bare empty array, which would read as "no active airspace here".
airspace:read also covers the pilot's saved planner files. The OpenAir
files a pilot saves at the end of the XC planner (/api/v1/airspace/files)
are private to that pilot, yet they sit under airspace:read rather than a
scope of their own. This is deliberate: an instrument that pulls airspace
should get the pilot's planned airspace with the same consent. It also means
an app or key granted airspace:read before these files existed can read
them without a new consent screen. A pilot who does not want that revokes the
app's access or the key from the developer dashboard (/developer).
Asking for fewer scopes later (downscoping)
When you refresh a token (grant_type=refresh_token) you may pass a
scope parameter narrower than the original grant. The returned
access+refresh pair will carry only the narrowed set, and the new
refresh token cannot widen back. This is useful when you've decided
your integration no longer needs (say) flights:write and you want to
remove that capability without forcing a new user-consent screen.
You cannot widen a scope on refresh. The server will return
invalid_scope. Get the user to re-authorise instead.
Consent screen
When a user authorises an app, they see a list of requested scopes with a short human description. The same scope catalog is applied identically on the server and the consent UI. Partners cannot override the description.
Write scopes are visually flagged.