Authentication
GameVault supports two primary authentication methods:
- Bearer Token (JWT) - for users logging in interactively. (The GameVault Client uses this method.)
- API-Key - for machine-to-machine and automated use cases.
This page shows you how to authenticate API requests using one of these methods.
Additionally this page provides details on how to set up SSO (Single Sign-On) via OAuth2, which allows users to authenticate using third-party identity providers like Google, Microsoft, Keycloak, etc.
Bearer Token (JWT) Authentication
JWT is the default method for user-based authentication. Include your access token in the Authorization header like so:
Authorization: Bearer <your_access_token>
Generating Tokens
You can generate a Bearer token using one of the login endpoints:
-
Basic Authentication: If enabled in your server configuration, authenticate via:
POST /api/auth/basic/loginwith your username and password. A user needs to be registered first using the registration endpoint.
-
OAuth2 Authentication: If OAuth2 is enabled in your server configuration, authenticate via:
GET /api/auth/oauth2/loginthrough your configured identity provider. This will automatically register the user on the server if they don't already exist.
On success, both methods return an access_token and refresh_token. You can use the access token for authenticated requests to the GameVault API. The refresh token can be used to request a new access token when the current one expires.
Failed logins and rate limiting
Login errors do not reveal whether a username exists, and both cases take the same amount of time. Failed password logins are also rate limited per client address and username: after AUTH_RATE_LIMIT_MAX_ATTEMPTS failures inside AUTH_RATE_LIMIT_WINDOW_SECONDS, the server answers with 429 Too Many Requests and a Retry-After header. Successful logins, token refreshes and SSO logins are never limited. The counters live in memory, so each server process tracks its own. Rate limiting is on by default and can be tuned with the AUTH_RATE_LIMIT variables on the Configuration page.
Token Expiration
Generated access tokens are valid for 5 minutes, and refresh tokens for 30 days. These durations can be adjusted on the Configuration page.
Refreshing Tokens
When your access token expires, request a new token pair using your refresh token by calling the POST /api/auth/refresh endpoint with your refresh token. Your current refresh token will be invalid after this call so make sure to always use the token received from the response for future token refreshes.
Revoking Tokens
You can revoke a token by calling the POST /api/auth/revoke endpoint with your refresh token. This will effectively log out the user, by blocking future token refreshes.
Access tokens stay valid until they expire, because they are checked without a database lookup. Enable AUTH_ACCESS_TOKEN_SESSION_BINDING_ENABLED on the Configuration page to bind every access token to its session, so revoking a session also invalidates the access tokens that belong to it.
API-Key Authentication (Machine-to-Machine)
GameVault also supports API-key-based authentication. This is perfect for bots, automation, and service-to-service calls, no need for login sessions.
Enabling API Key Support
To enable API-Key authentication, set the following environment variable:
AUTH_API_KEY_ENABLED=true
How to obtain an API Key
-
Register a user and fetch their API Key Register a user and use their Bearer token to fetch their API key via:
GET /api/users/meExample response:
{"id": "4","username": "gvbot_infra","api_key": "a1b2c3d4e5..." // this is your API key}
You can hide bot accounts from users by prefixing their usernames with gvbot_.
Making Authenticated API Requests
Include your API-key in the request headers like so:
X-Api-Key: a1b2c3d4e5...
Notes
- API keys do not expire, handle them carefully
- API keys currently can not be revoked or changed
- API keys are user-bound and inherit that user's permissions.
Setting Up OAuth2 Authentication (Single Sign-On)
Setting up single sign-on (SSO) using OAuth2 authentication for GameVault requires an identity provider (e.g. Google, Authelia, Keycloak, Microsoft, Discord, etc.).
Step by Step Guide
-
Enable OAuth2 authentication in your configuration.
-
Create an OAuth2 client in your chosen identity provider.
-
Add the Authorization URL and Token URL from your identity provider to the Configuration.
-
Enter your client ID and client secret into the Configuration.
-
Set the OAuth2 callback URL to your GameVault server URL appended with
/api/auth/oauth2/login(e.g.,https://demo.gamevau.lt/api/auth/oauth2/login). -
Test the authentication by accessing
/api/auth/oauth2/loginon your GameVault server. You will be redirected to your identity provider's login page. After logging in, you'll return to GameVault, and it will exchange the provided authorization code for an access token. It will automatically register the user using the data from your identity provider if they don't already exist. A successful response looks like this:{"id": "2","access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."} -
Authentication is now complete. Use the provided access token for authenticated requests to the GameVault API.
Verifying the ID token
Without further settings GameVault reads the user data from the id_token without checking its signature. For OpenID Connect providers switch verification on:
AUTH_OAUTH2_ISSUER_URL=https://auth.example.com/application/o/gamevault
AUTH_OAUTH2_VERIFY_ID_TOKEN=true
GameVault then fetches the JWKS through OpenID Connect discovery
({issuer}/.well-known/openid-configuration, or the configured
AUTH_OAUTH2_JWKS_URL), verifies signature, iss, aud and expiry, and sends a
nonce with the authorization request that has to come back inside the
id_token. If your provider does not echo the nonce, set
AUTH_OAUTH2_REQUIRE_NONCE=false. Providers that return no id_token at all
keep working: the server logs a warning and falls back to the decoded claims.
All four switches are described under AUTH.
Examples
You can find working example configurations for popular identity providers below to get an idea of how to set them up.
Google
AUTH_OAUTH2_CLIENT_ID=XXXXXXXXXXXX-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXX.apps.googleusercontent.com
AUTH_OAUTH2_CLIENT_SECRET=XXXXXX-XXXXXXXXXXXX-XXXXXXXXXXXX
AUTH_OAUTH2_AUTH_URL=https://accounts.google.com/o/oauth2/v2/auth
AUTH_OAUTH2_TOKEN_URL=https://oauth2.googleapis.com/token
AUTH_OAUTH2_USERINFO_URL=https://www.googleapis.com/oauth2/v3/userinfo
Discord
AUTH_OAUTH2_CLIENT_ID=XXXXXXXXXXXXXXXXXXXXXXXX
AUTH_OAUTH2_CLIENT_SECRET=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
AUTH_OAUTH2_AUTH_URL=https://discord.com/oauth2/authorize
AUTH_OAUTH2_TOKEN_URL=https://discord.com/api/oauth2/token
AUTH_OAUTH2_SCOPES=openid,email,identify
AUTH_OAUTH2_USERINFO_URL=https://discord.com/api/users/@me
Debugging OAuth2 Authentication
You can set the environment variable SERVER_LOG_LEVEL environment variable to debug to receive detailed logs about the authentication process.
Limitations
- Without plugins, only one OAuth2 Identity Provider can be used at a time.
- The OAuth2 implementation is RFC-compliant but basic (requires
openid,profile,email). Compatibility may vary depending on the identity provider. If you encounter issues using a popular identity provider, please report them on GitHub. Include details about your identity provider and debug logs in the issue.