> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skyvexsoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stratos Core API

> Install the Stratos Core API module on your phpVMS 7 install — the required base for every Stratos integration.

The **Stratos Core API** is a phpVMS 7 module that exposes the endpoints the Stratos desktop client needs: pilot authentication, reference data, and the flight lifecycle (start → update → complete → cancel). It's required by every Stratos integration — everything else (Logbook, screenshots, future modules) builds on top of it.

* **Repository:** [github.com/SkyvexSoftware/stratos-core-api](https://github.com/SkyvexSoftware/stratos-core-api)
* **Latest release:** [GitHub Releases](https://github.com/SkyvexSoftware/stratos-core-api/releases/latest)
* **API reference:** [Stratos VA API](/api-reference/introduction) — full endpoint contract, useful when you're forking the module or implementing the same surface in a non-phpVMS stack
* **License:** MIT

## What it adds

The module mounts these endpoints under `/api/stratos` on your phpVMS install. All require a Bearer token (the pilot's `users.api_key`) except the handshake and the credentials login.

```
GET    /api/stratos/                          handshake — version + handler
POST   /api/stratos/pilot/login               credentials login
GET    /api/stratos/pilot/verify              authenticated pilot profile
GET    /api/stratos/pilot/statistics          flight hours, average landing rate, etc.
GET    /api/stratos/data/aircraft             fleet list
GET    /api/stratos/data/airports             airport directory
GET    /api/stratos/data/announcements        VA announcements feed
GET    /api/stratos/flights/bookings          pilot's current bids
GET    /api/stratos/flights/bookings/{bid}/aircraft   aircraft eligible for a bid
POST   /api/stratos/flights/change-aircraft           change a bid's aircraft
POST   /api/stratos/flights/start             begin tracking a booked flight
POST   /api/stratos/flights/update            position / phase update
POST   /api/stratos/flights/complete          file PIREP
POST   /api/stratos/flights/cancel            cancel active flight
POST   /api/stratos/flights/unbook            drop a bid
```

Every endpoint is pure phpVMS-native: pilots in `users`, flights in `flights` and `acars`, PIREPs in `pireps`, custom metadata in `pirep_field_values`. The module owns zero tables of its own — uninstalling it leaves your phpVMS database exactly as it was.

## Install

You'll need a working phpVMS 7 install with admin access.

<Steps>
  <Step title="Download the module">
    Grab the latest `module.zip` from the [releases page](https://github.com/SkyvexSoftware/stratos-core-api/releases/latest).
  </Step>

  <Step title="Upload via the admin UI">
    In your phpVMS admin, navigate to **Admin → Modules → Add New Module**. Upload the `module.zip` you just downloaded. phpVMS will extract it into your `modules/StratosCore/` directory automatically.
  </Step>

  <Step title="Enable the module">
    Back on the **Modules** list, find `StratosCore` and click **Enable**.
  </Step>

  <Step title="Clear caches">
    From a shell on your phpVMS server:

    ```bash theme={null}
    php artisan optimize:clear
    ```

    This flushes phpVMS's module manifest cache so the new module's routes become available immediately rather than after the cache's 6-hour TTL expires.
  </Step>

  <Step title="Verify">
    Hit your handshake endpoint in a browser or with `curl`:

    ```bash theme={null}
    curl https://crew.youva.com/api/stratos/
    ```

    You should get a JSON response like:

    ```json theme={null}
    {"api_version": "0.2.3", "handler": "Stratos"}
    ```

    If you get a 404 or the phpVMS welcome page, the cache clear didn't take — try `php artisan route:clear && php artisan cache:clear` and check again.
  </Step>
</Steps>

## Configure Skyvex to use it

On your [Stratos airline page](https://skyvexsoftware.com/login), under **Crew System Integration**:

* **Stratos VA API base URL** — set this to your phpVMS URL plus `/api/stratos`. e.g. `https://crew.youva.com/api/stratos`.
* **Auth method** — choose **Credentials** if pilots will sign in with their phpVMS username + password, or **OAuth** if you've set up [OAuth on your phpVMS install](/guide/oauth-setup).

Save and click **Test connection** — Skyvex hits the handshake endpoint and reports back.

## Pilot authentication

Pilots authenticate to the Core API with their phpVMS-issued `api_key`. The flow is:

1. Pilot signs into your phpVMS site, generates an API key on their profile page (or your VA does it for them on first onboarding).
2. The Stratos desktop client either prompts the pilot for that key directly (credentials mode), or completes an OAuth flow that returns it (OAuth mode — recommended, see [OAuth Setup](/guide/oauth-setup)).
3. Every subsequent Stratos API call sends the key as `Authorization: Bearer <api_key>`.

The `StratosAuth` middleware resolves the key against the `users.api_key` column and attaches the user to the request. Downstream Stratos modules (Logbook, etc.) reuse the same middleware — pilots authenticate once.

## Troubleshooting

### `Class "Modules\\StratosCore\\Providers\\..." not found` after install

phpVMS caches the module manifest in `bootstrap/cache/stratos_core_module.php` and in Laravel's main cache under the `phpvms-modules` key. If you installed the module but those caches are stale, phpVMS will try to instantiate provider classes from a path that doesn't yet exist on disk.

Fix:

```bash theme={null}
php artisan optimize:clear
```

If that's not enough (rare — usually only when the module was previously installed at a different path), also delete `bootstrap/cache/stratos_core_module.php` manually and re-run the command.

### Endpoints return 404 but the module shows as enabled

The route cache hasn't picked up the new module. Run:

```bash theme={null}
php artisan route:clear
php artisan optimize:clear
```

Then hit the handshake again.

### Pilots get 401 with a valid API key

Confirm:

* The `Authorization` header is exactly `Bearer <key>` (case-sensitive scheme, single space, no quotes around the key)
* The key matches the value in `users.api_key` for the pilot
* The pilot's account is active (`users.state = 1`)

If the key is correct, check `storage/logs/laravel.log` for the auth attempt — `StratosAuth` logs failures with the offending header for diagnosis.

## Updating

Releases go out via the [GitHub release feed](https://github.com/SkyvexSoftware/stratos-core-api/releases). To update an existing install:

1. Download the new `module.zip`.
2. **Admin → Modules → Add New Module** — upload it. phpVMS will overwrite the existing files in place; your `modules.enabled` row is preserved.
3. Run `php artisan optimize:clear`.

Migrations (if any ever ship) auto-run on enable; the current release ships zero migrations because Core owns no tables.

## Contributing

The repo accepts PRs. Bug reports go in [Issues](https://github.com/SkyvexSoftware/stratos-core-api/issues) — please include the phpVMS version, PHP version, and a relevant snippet from `storage/logs/laravel.log`.