Authentication

Learn how to authenticate with the VPT API using JWT tokens for secure, seamless access to all endpoints.

Overview

The VPT API uses JWT (JSON Web Tokens) for authentication. JWTs provide a secure, stateless way to authenticate requests without storing session data on the server.

Authentication Flow

JWT Authentication

JWT tokens are self-contained and include all necessary information to validate requests. They are signed using the HS256 algorithm to ensure integrity.

Developer Key Access Levels

The developer key determines the level of user information returned during authentication. There are three access levels:

Login

To obtain a JWT token, send a POST request to the API with your credentials:

Request Parameters

The request body uses a structured format with query, devKey, and data at the root level:

curl -X POST "https://api.virtualperformancetool.com/api" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "login",
    "devKey": "your_dev_key",
    "data": {
      "email": "your_email@example.com",
      "password": "your_password"
    }
  }'

const response = await fetch('https://api.virtualperformancetool.com/api', {
    method: 'POST',
    headers: {
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        query: 'login',
        devKey: 'your_dev_key',
        data: {
            email: 'your_email@example.com',
            password: 'your_password'
        }
    })
});

const data = await response.json();

if (data.success) {
    // Store the token for future requests
    const token = data.token;
    localStorage.setItem('vpt_token', token);
}

<?php
$ch = curl_init('https://api.virtualperformancetool.com/api');

$data = [
    'query' => 'login',
    'devKey' => 'your_dev_key',
    'data' => [
        'email' => 'your_email@example.com',
        'password' => 'your_password'
    ]
];

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST => true,
    CURLOPT_POSTFIELDS => json_encode($data),
    CURLOPT_HTTPHEADER => [
        'Content-Type: application/json'
    ]
]);

$response = curl_exec($ch);
$result = json_decode($response, true);

if ($result['success']) {
    $token = $result['token'];
    // Store token for future use
    $_SESSION['vpt_token'] = $token;
}

import requests

response = requests.post(
    'https://api.virtualperformancetool.com/api',
    json={
        'query': 'login',
        'devKey': 'your_dev_key',
        'data': {
            'email': 'your_email@example.com',
            'password': 'your_password'
        }
    }
)

data = response.json()

if data.get('success'):
    token = data['token']
    # Store token for future use

Successful Response

{
  "success": true,
  "apiVersion": "1.3.6",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires": "2026-02-23T18:59:05+01:00",
  "expiresIn": 2592000,
  "user": {
    "email": "john.doe@example.com",
    "firstname": "John",
    "lastname": "Doe",
    "crewcode": "JD001",
    "rank": "CAPT",
    "streamingAlias": "LivePro",
    "streamingActive": 0,
    "virtualAirline": "VPT Airlines",
    "tokenVersion": 1,
    "subscription": {
      "title": "VPT Pro Annual",
      "level": 3,
      "status": "ACTIVE",
      "type": "pro",
      "expiry": "2026-12-31T23:59:59+01:00",
      "daysRemaining": 250,
      "isActive": true,
      "isExpired": false,
      "isTrial": false,
      "isPaused": false,
      "pauseUntil": null,
      "isAutoRenew": true,
      "paymentMethod": "paypal",
      "capabilities": {
        "isNotam": true,
        "isNnc": true,
        "isMel": true,
        "isCdl": true,
        "isCommercial": false,
        "isFleetDatabase": true,
        "maxCalculation": 1000
      },
      "preview": {
        "active": false,
        "reason": null,
        "allowedAirports": [],
        "message": null
      }
    },
    "userPreferences": {
      "defaultUnit": "METRIC",
      "defaultAircraftOnStartup": {
        "file": "320-212-CFM56-5A3.json",
        "userRegistration": null,
        "vaFleet": null
      },
      "takeoff": {
        "customizeStandardEngineFailureProcedure": true,
        "customizedText": "Maintain [RWY_TRACK]° to 25 NM...",
        "displayEngineFailureInFull": true
      }
    }
  }
}

The subscription object

The user.subscription object reflects the current subscription state for the account. It is included at MEDIUM and FULL access levels only. There is one and only one subscription object per user; the airport restriction (when applicable) is carried by the embedded preview block.

When the user has no row in the subscriptions table, the API synthesizes a PREVIEW subscription from the preview product (currently VPT Pro Annual, with the word “Annual” rewritten to “Demo” in the title). The synthesized object is isActive = true with the embedded preview.active = true block, so the client can render the full Pro UI; the API enforces the airport restriction server-side via preview.allowedAirports.

The embedded subscription.preview block

Every subscription object carries an embedded preview block. When preview.active is true the user is granted the full Pro UI but the API only accepts requests against the airports listed in preview.allowedAirports; requests against any other ICAO are rejected server-side.

preview.active is true when:

• The user has no real subscription row (synthesized PREVIEW subscription from product id 3, VPT Pro Demo).
• The user's subscription date_end is in the past.

For real, currently-active subscriptions (including commercial subscriptions manually granted with no payment gateway), preview.active is false, allowedAirports is empty and the user has unrestricted access.

MEDIUM Access Level includes additional fields:

• simbriefId - SimBrief account ID
• dateJoined - Account creation timestamp
• lastConnected - Last login timestamp
• Extended userPreferences including: settingsLocked, displayIntegratedTutorial, weather, performance, export, simbrief, efb groups

Error Response

{
  "success": false,
  "error": {
    "message": "Invalid email or password.",
    "code": "AUTH_INVALID_CREDENTIALS",
    "status": 401
  }
}

Using Tokens

Once you have a JWT token, include it in the Authorization header of all API requests using the Bearer scheme:

Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Example: Protected Request

curl -X POST "https://api.virtualperformancetool.com/api" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "performance",
    "data": { [...] }
  }'

Token Refresh (Sliding Expiration)

To provide a seamless experience, the API implements sliding expiration. When a token is used and has less than 7 days remaining before expiration, a new token is automatically issued.

How It Works

1. Token is valid for 30 days from issuance
2. When token has < 7 days remaining and a request is made:
3. The API returns a new token in the response
4. Both old and new tokens remain valid until expiration
5. Your application should store and use the new token

Response with Refreshed Token

When your token is refreshed, the response includes a new token:

{
  "success": true,
  "data": {
    // ... your requested data
  },
  "token_refreshed": true,
  "new_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expiresIn": 2592000
}

Handling Refreshed Tokens

async function apiRequest(endpoint, data) {
    const token = localStorage.getItem('vpt_token');
    
    const response = await fetch(endpoint, {
        method: 'POST',
        headers: {
            'Authorization': `Bearer ${token}`,
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(data)
    });
    
    const result = await response.json();
    
    // Check if token was refreshed
    if (result.token_refreshed && result.new_token) {
        localStorage.setItem('vpt_token', result.new_token);
        console.log('Token refreshed automatically');
    }
    
    return result;
}

Token Revocation

In case of account compromise, all existing tokens can be invalidated by changing the account password. This is implemented using a token version mechanism.

How Token Revocation Works

1. Each JWT contains a version number (v claim)
2. The user's current token version is stored in the database
3. On each request, the token version is verified against the database
4. When password is changed, the token version is incremented
5. All tokens with older versions become invalid

Handling Revoked Tokens

When a token has been revoked, the API returns:

{
  "success": false,
  "error": "Token has been revoked",
  "error_code": "AUTH_TOKEN_REVOKED"
}

Your application should handle this by prompting the user to log in again:

async function apiRequest(endpoint, data) {
    const response = await fetch(endpoint, { /* ... */ });
    
    if (response.status === 401) {
        const error = await response.json();
        
        if (error.error_code === 'AUTH_TOKEN_REVOKED') {
            // Clear stored token
            localStorage.removeItem('vpt_token');
            
            // Redirect to login
            window.location.href = '/login?reason=token_revoked';
            return;
        }
    }
    
    return response.json();
}

Logout All Devices

Invalidate all existing JWT tokens across every device and session. This uses the same token version mechanism as password changes, but without requiring a password change. A new token is returned so the current device stays logged in.

Request Parameters

Request Example

curl -X POST "https://api.virtualperformancetool.com/api" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "logoutAll"
  }'

const response = await fetch('https://api.virtualperformancetool.com/api', {
    method: 'POST',
    headers: {
        'Authorization': `Bearer ${token}`,
        'Content-Type': 'application/json'
    },
    body: JSON.stringify({
        query: 'logoutAll'
    })
});

const data = await response.json();

if (data.success) {
    // Replace stored token with the new one
    localStorage.setItem('vpt_token', data.token);
    console.log('Logged out from all other devices');
}

Successful Response

{
  "success": true,
  "message": "Successfully logged out from all other devices.",
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires": "2026-04-20T18:59:05+01:00",
  "expiresIn": 2592000
}

Response Fields

Next Steps

Now that you understand authentication, you're ready to: