docs: write authentication section

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