auth

Author: Alfagun74

docs/advanced-usage/authentication.md

@@ -4,20 +4,48 @@
 This documentation is still being written and the features are under development. Please check back later for updates.
 :::
 
-## How to Authenticate Your API Requests
+GameVault supports two primary authentication methods:
 
-Most API requests require authentication using a JSON Web Token (JWT). Include this token in the `Authorization` header of each request in the following format:
+1. **Bearer Token (JWT)** – for users logging in interactively. (The GameVault Client uses this method.)
+2. **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)](#setting-up-oauth2-authentication-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:
 
 ```http
-Authorization: Bearer <your_token>
+Authorization: Bearer <your_access_token>
 ```
 
 ### Generating Tokens
 
-You can generate a Bearer token using one of the `login` endpoints:
+You can generate a Bearer token using one of the login endpoints:
+
+- **Basic Authentication:**
+  If enabled in your [server configuration](../server-docs/configuration.md#auth), authenticate via:
+
+  ```http
+  POST /api/auth/basic/login
+  ```
+
+  with your username and password. A user needs to be registered first using the registration endpoint.
+
+- **OAuth2 Authentication:**
+  If [OAuth2](#setting-up-oauth2-authentication-single-sign-on) is enabled in your [server configuration](../server-docs/configuration.md#auth), authenticate via:
+
+  ```http
+  GET /api/auth/oauth2/login
+  ```
 
-- **Basic Authentication:** If Basic Authentication is enabled, authenticate via `POST /api/auth/basic/login` with your username and password.
-- **OAuth2 Authentication:** If [OAuth2 authentication](#setting-up-oauth2-authentication-single-sign-on) is enabled, authenticate via `GET /api/auth/oauth2/login` through your configured identity provider.
+  through 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.
+
+### Token Expiration
 
 Generated access tokens are valid for **5 minutes**, and refresh tokens for **30 days**. These durations can be adjusted on the [Configuration](../server-docs/configuration.md) page.
 
@@ -29,6 +57,55 @@ When your access token expires, request a new token pair using your refresh toke
 
 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.
 
+## 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:
+
+```env
+AUTH_API_KEY_ENABLED=true
+```
+
+### How to obtain an API Key
+
+1. **Register a user and fetch their API Key**
+   Register a user and use their Bearer token to fetch their API key via:
+
+   ```http
+   GET /api/users/me
+   ```
+
+   Example response:
+
+   ```json
+   {
+     "id": "4",
+     "username": "gvbot_infra",
+     "api_key": "a1b2c3d4e5..." // this is your API key
+   }
+   ```
+
+:::tip You can hide Bots
+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:
+
+```http
+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.).
@@ -54,7 +131,7 @@ Setting up single sign-on (SSO) using OAuth2 authentication for GameVault requir
 
 ### Debugging OAuth2 Authentication
 
-- Set the environment variable `SERVER_LOG_LEVEL` environment variable to `debug` to receive detailed logs about the authentication process.
+You can set the environment variable `SERVER_LOG_LEVEL` environment variable to `debug` to receive detailed logs about the authentication process.
 
 ### Limitations
 

docs/server-docs/websockets.md

@@ -35,4 +35,4 @@ For server owners who wish to disable activities, it's as simple as setting the
 
 ## Security
 
-Each user is assigned a randomly generated Socket Secret that they can retrieve at `/api/users/me`. This secret must be included in the headers (X-Socket-Secret) of every subsequent Socket.IO Handshake request to the server.
+Each user is assigned a randomly generated API-Key, which they can retrieve at `/api/users/me`. This api-key must be included in the headers (X-Api-Key) of every subsequent Socket.IO Handshake request to the server.