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 (planned endpoint) | Stable |
flights:write | Upload IGC files to the user's logbook | Stable |
flights:delete | Permanently remove flights | Stable, destructive |
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 and waypoint collections; browse the shared task library | Stable |
tasks:write | Save competition tasks and waypoint collections 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 and temporary activations | 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 the destructive scopes from arbitrary users. -
API keys cannot grant
flights:delete. The risk profile of a long-lived key bundled into a personal script is too high for a destructive scope — use OAuth for delete flows. -
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".
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.
Dangerous scopes (write, delete) are visually flagged.