API Reference

Gatekeeper API

Authentication server endpoints for license validation, Patreon OAuth, and Cloudflare Tunnel provisioning.

Base URL

https://auth.vryionic.com:8443

All endpoints below are relative to this base URL. Responses are JSON unless otherwise noted.

Health Check

GET /health

Returns the server status and version. Use this to verify the Gatekeeper is reachable.

Response:

{
  "status": "ok",
  "version": "1.0.0"
}

Remote Configuration

GET /config

Returns the current remote configuration consumed by the VMSC client. This includes tier definitions, authentication URLs, upgrade prompts, and grace period settings.

Response: A JSON object containing tier limits, feature flags, and UI configuration. The shape of this payload may change between versions.

Patreon OAuth

GET /auth/patreon

Starts the Patreon OAuth flow. The server redirects the user's browser to the Patreon authorization page. VMSC opens this URL in the system browser during the login process.

Response: 302 Redirect to Patreon.

GET /auth/callback

OAuth callback endpoint. Patreon redirects here after the user authorizes the application. The server exchanges the authorization code and redirects back to the VMSC app with a temporary auth code.

Query Parameters:

ParameterDescription
codeAuthorization code from Patreon
stateCSRF state token

Response: 302 Redirect back to the VMSC deep link with an auth code.

Token Exchange

POST /auth/exchange

Exchanges a temporary auth code (received from the OAuth callback) for a signed JWT and the user's resolved tier.

Request Body:

{
  "code": "auth-code"
}

Response:

{
  "token": "jwt-string",
  "tier": "premium"
}

Validate / Refresh JWT

POST /validate

Validates an existing JWT and returns a refreshed token if the session is still valid. VMSC calls this on startup and periodically to keep the license active.

Request Header:

Authorization: Bearer <jwt>

Response: A new JWT with an extended expiration, or an error if the token is invalid or the subscription has lapsed.

Tunnel Provisioning

Premium Only

Tunnel endpoints require a valid Premium JWT in the Authorization header.

POST /tunnels/provision

Creates a new Cloudflare Tunnel for the authenticated user, enabling remote overlay access without port forwarding.

Request Body:

{
  "user_id": "patreon-id"
}

Response:

{
  "tunnel_id": "uuid",
  "tunnel_token": "eyJ...",
  "public_url": "https://abc123.vryionic.com",
  "subdomain": "abc123"
}

GET /tunnels/status/:userId

Returns the current status of a user's tunnel, including whether it is active and its public URL.

DELETE /tunnels/:userId

Deletes the tunnel associated with the given user ID and releases the subdomain.