Authentication

JWT token lifecycle, payload structure, and usage for the Open VTS API.

Token Lifecycle

Open VTS uses a two-token system. The access token authenticates API requests while the refresh token obtains a new access token without re-entering credentials.

Token	TTL	Purpose
Access Token (JWT)	`24 hours`	API authorization
Refresh Token	`7 days`	Obtain new access token

Call POST /auth/refresh-token with a valid refresh token to get a new access token before the current one expires.

JWT Payload

The decoded JWT contains the user identity, role, and expiration timestamps.

Decoded Payload

{
  "sub": 123,
  "username": "john_doe",
  "email": "john@example.com",
  "role": "ADMIN",
  "iat": 1709884800,
  "exp": 1709971200
}

Field	Type	Description
`sub`	number	User ID
`username`	string	Username
`email`	string	User email
`role`	string	User role (SUPERADMIN, ADMIN, USER, etc.)
`iat`	number	Issued-at timestamp (Unix)
`exp`	number	Expiration timestamp (Unix)

Using Tokens

Pass the JWT token in the Authorization header as a Bearer token on every authenticated request.

HTTP Request

GET /admin/vehicles HTTP/1.1
Host: api.openvts.io
Authorization: Bearer eyJhbGciOiJIUzI1NiIs...
Content-Type: application/json

Auth Requirement Notes

Public endpoints (auth, health) do not require a token.

Superadmin endpoints require a SUPERADMIN role token.

Admin endpoints require an ADMIN (or higher) role token.

User endpoints require a USER (or higher) role token.

Expired tokens return 401 Unauthorized — use the refresh flow.

Tokens with insufficient permissions return 403 Forbidden.

Overview

Response Envelope