From 9b93cd97a6fba5cc4e77aaf93613302721622fe7 Mon Sep 17 00:00:00 2001
From: Cedric Hornberger <ceddi.hornberger@gmx.de>
Date: Sat, 9 May 2026 23:56:14 +0200
Subject: [PATCH] docs: write authentication section

---
 docs/API.md | 27 ++++++++++++++++++++++++++-
 1 file changed, 26 insertions(+), 1 deletion(-)

diff --git a/docs/API.md b/docs/API.md
index 50808e5..900168f 100644
--- a/docs/API.md
+++ b/docs/API.md
@@ -35,7 +35,32 @@ All other endpoints require authentication (see [Section 2](#2-authentication)).
 
 ## 2. Authentication
 
-_TODO_
+The server uses **OAuth2 Resource Server** authentication with **Google ID JWT tokens**.
+
+### How it works
+
+1. The client authenticates with Google and receives a Google ID JWT.
+2. Every protected API request must include this token in the header:
+
+```
+Authorization: Bearer <google-id-jwt>
+```
+
+3. The server validates the JWT signature and extracts the `sub` claim (Google User ID).
+4. The `sub` value is used to look up the registered `AppUser` in the database via `AuthenticatedUserResolver`.
+5. If no `AppUser` exists for that Google ID, the request is rejected with **403 Forbidden**.
+
+### Test profile
+
+When the application runs under the `test` Spring profile (`-Dspring.profiles.active=test`), **all security is disabled** — every endpoint is accessible without a token. This is used for automated tests only.
+
+### User registration flow
+
+Before a user can call any protected endpoint they must first be registered:
+
+1. Authenticate with Google to obtain a Google ID JWT.
+2. Call `POST /api/users/createUser` with the JWT's `sub` value as `googleId` and a chosen `username`.
+3. All subsequent protected calls use the same JWT — the server resolves the caller automatically.
 
 ## 3. Rate Limiting