API

vAMSYS provides two APIs for integrating with external systems. Both are managed from the same page in Orwell and have interactive OpenAPI documentation.

Accessing API Settings

In Orwell, go to Settings → API → API v3. You need the Can See API Settings permission. Airlines on trial do not have access to API settings.

The Two APIs

	Operations API	Pilot API
Purpose	Server-to-server integration — manage fleet, routes, pilots, PIREPs, activities, and more	Pilot-facing applications — third-party apps that authenticate pilots and access their data
Grant Type	Client Credentials	Authorization Code + PKCE
Authentication	Client ID + Secret	OAuth PKCE flow — no secret, pilot authorises in browser
Documentation	Available at /docs/operations on your vAMSYS instance	Available at /docs/pilot on your vAMSYS instance

Creating a Client

Click New Client and select the grant type for the API you want to use.

Operations API Client (Client Credentials)

Provide a client name and optionally select scopes to restrict what the client can access. If no scopes are selected, the client has unrestricted access to all endpoints.

Available scopes:

• ops:read — all GET endpoints. Safe to embed in client-side JavaScript for public displays.

• ops:config:write — manage fleet, aircraft, airports, hubs, ranks, badges, routes, and related configuration.

• ops:flights:write — manage bookings, PIREP comments, points, notes, and pilot data.

• ops:moderation:write — accept, reject, and invalidate PIREPs; ban and delete pilots; manage registrations and transfers.

• ops:activities:write — manage events, tours, rosters, focus airports, community goals, and challenges.

After creation, the client ID and secret are shown once. Store the secret securely — it cannot be retrieved later. Use Reset Secret to generate a new secret if needed (this revokes all existing tokens).

Pilot API Client (Authorization Code + PKCE)

Provide a client name, redirect URI, privacy policy URL, and select the scopes your application needs.

• Redirect URI — HTTPS URL or custom URI scheme for native apps (e.g., myapp://callback). Plain HTTP is not allowed.

• Privacy Policy URL — must be a publicly accessible privacy policy covering how pilot data is handled.

• Allowed Scopes — select which pilot data your application can access (identity, pilot profile, flights, activities).

Managing Clients

From the API page you can:

• View request statistics — see today, this week, this month, and all-time request counts per client.

• Edit client settings — update the name, redirect URI, privacy policy, or allowed scopes.

• Revoke a client — stop a client requesting new tokens without deleting it. Tokens it already holds keep working until they expire.

• Delete a client — remove a client from the list. Deleting does not revoke the tokens it has already issued, so use Reset Secret first if the secret has leaked.

Request Logs

Below the client table, a live request log shows recent API requests with method, endpoint, status code, response time, and IP address. The log refreshes automatically every 30 seconds. Filter by client, HTTP method, status code range, or date.

API Documentation

Interactive API documentation is available directly on your vAMSYS instance:

• Operations API — /docs/operations

• Pilot API — /docs/pilot

The documentation is auto-generated from the codebase and includes all endpoints, request/response schemas, and authentication requirements. Links to both are also shown at the bottom of the API settings page in Orwell.

Troubleshooting

If the vAMSYS API is unreachable, your integration cannot connect, or requests that worked yesterday now time out or are refused, work through these before anything else. The endpoint reference above is generated from the code and is always current — what it cannot tell you is why a request that looks correct is being rejected. Almost every report of the API being down turns out to be one of the three causes below.

Requests suddenly return 401

Access tokens expire 15 days after they are issued, and refresh tokens after 30 days. An integration that authenticated once and cached its token will start failing on day 16. Request a new token rather than reusing a stored one, and refresh before the token expires.

Resetting a client secret also revokes every existing access token for that client immediately. If you reset a secret, update everything using the old one at the same time.

Pilots cannot authorise your Pilot API client

A new Pilot API client is created revoked and stays that way until the VA Owner opens the API settings page and uses Attest & Activate. Until then pilots cannot authorise it. Only the VA Owner can do this — no other staff member sees the action, however senior.

The API settings page is missing in Orwell

Two things hide it. Virtual Airlines on a free trial have no API access at all, so the page does not appear until the VA subscribes. Otherwise you need the Can See API Settings permission — ask an Owner to grant it in Settings → Staff.

Permissions

Permission	Grants
Can See API Settings	Access to API client management, request logs, and documentation links

Note: Only the VA Owner can attest and activate Pilot API clients.