Authentication API

Base URL: https://app.kvmfleet.io/v1

All endpoints except login return 401 if the access token is missing or expired.

Initiate Google OIDC login flow.

# Returns a redirect URL for Google OAuth consent
curl https://app.kvmfleet.io/v1/auth/google/login

{
  "redirect_url": "https://accounts.google.com/o/oauth2/v2/auth?client_id=...&redirect_uri=..."
}

Google SSO callback

After Google consent, the browser is redirected here. Not called directly.

GET /v1/auth/google/callback?code=...&state=...

Returns:

{
  "access_token": "eyJ...",
  "refresh_token": "eyJ...",
  "expires_in": 900,
  "user": {
    "id": "usr_abc123",
    "email": "user@example.com",
    "org_id": "org_xyz789",
    "role": "admin"
  }
}

Token lifetimes

Token	Lifetime
Access token	15 minutes
Refresh token	7 days

Refresh token

curl -X POST https://app.kvmfleet.io/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "eyJ..."}'

{
  "access_token": "eyJ...",
  "expires_in": 900
}

Returns 401 if the refresh token is expired or revoked.

Logout

Revokes the refresh token.

curl -X POST https://app.kvmfleet.io/v1/auth/logout \
  -H "Authorization: Bearer $TOKEN"

{"ok": true}

Using access tokens

Include the access token in the Authorization header for all API requests:

curl https://app.kvmfleet.io/v1/devices \
  -H "Authorization: Bearer eyJ..."

Error responses

Status	Meaning
`401`	Token missing, expired, or invalid
`403`	Valid token but insufficient role