Skip to main content

Authentication

KubeVision supports local passwords, TOTP, passkeys/security keys, directory accounts, and configured OAuth/OIDC providers. Successful authentication issues an access token and refresh token using the TTLs configured by the operator.

Password or Directory Login​

POST /api/v1/auth/login
Content-Type: application/json

{"username":"admin","password":"your-password"}

Directory users use the same endpoint. When directory login is enabled, the backend resolves the identity and group-to-role mapping according to the saved directory policy.

If TOTP is enabled, login returns business code 40102 and a short-lived temporary token. Complete it with one of these public endpoints:

MethodPathPurpose
POST/auth/2fa/verifyVerify a TOTP code
POST/auth/2fa/recoveryConsume a recovery code

Refresh​

POST /api/v1/auth/refresh
Content-Type: application/json

{"refreshToken":"<refresh-token>"}

Use the returned access token in protected requests:

Authorization: Bearer <access-token>

OAuth and OIDC​

MethodPathPurpose
GET/auth/oauth/providersList configured providers
GET/auth/oauth/:provider/authorizeBegin authorization
GET/auth/oauth/:provider/callbackProvider callback

The provider name must match an entry in oauth.providers. KubeVision supports OIDC discovery through issuer, or explicit authorization, token, and user-info URLs for standard OAuth providers. The callback URL must exactly match the URL registered with the provider.

Passkeys and Security Keys​

First check whether public-key authentication is enabled:

GET /api/v1/auth/public-key/config

Authentication is a two-step WebAuthn exchange:

MethodPath
POST/auth/public-key/login/begin
POST/auth/public-key/login/finish

Registration and credential management require an existing authenticated session and are listed in the Endpoint Index. Browser origin, relying-party ID, and HTTPS requirements are described in Authentication Providers.

Token Security​

  • Store access tokens only where the KubeVision client expects them; do not put bearer tokens in arbitrary URLs.
  • Changing a user's password or security state can invalidate existing sessions through the user's token version.
  • Store TOTP recovery codes securely. They are intended for one-time recovery.
  • Use TLS for login, OAuth callbacks, WebAuthn, and all authenticated APIs.