Authentication¶
vxbeamer comes with two authentication methods:
User authentication via OIDC, for interactive use from the frontend.
API keys (via
API_KEYS), for integration with scripts.
User authentication¶
The OIDC provider must support:
PKCE flow — the frontend performs the authorization code flow with PKCE and exchanges the resulting ID token for a session with the backend.
Discovery document — the provider must expose its configuration at the standard
/.well-known/openid-configurationpath.CORS — cross-origin requests must be allowed, since the frontend will contact the provider directly from the browser.
Restricted token issuance — the provider must only issue ID tokens to authorized users. There is no built-in user whitelist in vxbeamer itself, so access control must be enforced at the provider level.
Authentik is a self-hosted, open-source identity provider that meets all of these requirements.
Pairing a client¶
Clients that cannot easily sign in themselves (a PWA on iOS, the Android app, anything on a different machine from the browser you are signed in on) pair instead. Open /pair on your backend, sign in, and it shows a one-time pairing link and QR code. Open the link in the client, scan the QR code, or paste the link into its pairing box. The link carries the backend’s address and a 12-character code; the client redeems the code at POST /auth/pair for its own session.
Codes are valid for two minutes and work once. They are kept in memory, so a backend running several instances would need to share them.
The /pair page runs the OIDC code flow itself, so the provider must allow https://<your-backend>/pair as a redirect URI. Register it as an exact match, not a wildcard. Set PUBLIC_URL if the backend sits behind a proxy and the link should not use the address it sees.
API keys (personal access tokens)¶
Set the API_KEYS environment variable in the format <sub>:<key>. In case of multiple keys, separate by commas:
API_KEYS=your-sub-claim:my-secret-key,your-sub-claim:another-secret
To find your sub claim:
Pair the web app with your backend (see Pairing a client)
Open Settings (⚙️ icon)
Copy your
subfrom the “Signed in” section
The <sub> must match the sub claim of your OIDC user. You can have multiple keys for the same user (useful for key rotation or different integrations).
API keys are not used directly for authenticated requests. Instead, scripts exchange them for short-lived access tokens via POST /auth/token. This keeps all authentication consistent: protected endpoints only accept session tokens, regardless of whether they came from OIDC or API key exchange.
Access tokens¶
All protected endpoints require an access token. Pass it as:
Authorization: Bearer <token>header, or?access_token=<token>query parameter
Token flow¶
For OIDC users (interactive frontend):
Exchange OIDC id_token for access & refresh tokens:
POST /auth/sessionwithid_tokenAccess token (15 min TTL) is used for protected endpoints
When access token < 10 minutes remaining, refresh both tokens:
POST /auth/refreshwithrefresh_tokenRefresh token is valid for 3 days from the last refresh
For API keys (scripts/integrations):
Exchange API key for access token:
POST /auth/tokenwithapi_keyAccess token (15 min TTL) is used for protected endpoints
No refresh token is issued; obtain a new access token by exchanging the API key again