# API Specification: Hitelesítés és Felhasználói Profil

Ez a dokumentum a felhasználó hitelesítéshez (login) és a felhasználói profil lekéréséhez tartozó backend szerződést (API specifikációt) írja le.

## 1. Hitelesítési Mód
A backend **JWT (JSON Web Token)** alapú hitelesítést használ.
Az API végpontok (pl. profil lekérése) meghívásakor az access tokent a HTTP Header-ben kell átadni:
`Authorization: Bearer <access_token>`

Megjegyzés: A rendszer a `refresh_token`-t mind a JSON válaszban, mind egy HTTPOnly, Secure, SameSite=lax cookie-ban (`refresh_token` néven) visszaadja.

## 2. Bejelentkezés (Login) API

- **Végpont URL:** `POST /api/v1/auth/login`
- **Content-Type:** `application/x-www-form-urlencoded`

### Várt Request Body (Form Data)
A végpont az OAuth2PasswordRequestForm szabványt követi.

| Mező | Típus | Kötelező | Leírás |
|---|---|---|---|
| `username` | string | Igen | A felhasználó email címe. |
| `password` | string | Igen | A felhasználó jelszava. |
| `remember_me` | boolean | Nem | `true` esetén hosszabb lejárati idejű tokent ad (alapértelmezés: `false`). |
| `grant_type` | string | Nem | Értéke általában `password` (OAuth2 specifikáció szerint). |

### Visszaadott Response (JSON)
Sikeres bejelentkezés esetén (HTTP 200 OK):

```json
{
  "access_token": "eyJhbGciOiJIUzI1...",
  "refresh_token": "eyJhbGciOiJIUzI1...",
  "token_type": "bearer",
  "is_active": true
}
```

## 3. Felhasználói Profil Lekérése (Current User)

- **Végpont URL:** `GET /api/v1/users/me` (Létezik egy alias is: `GET /api/v1/auth/me`)
- **Hitelesítés:** Kötelező (Header: `Authorization: Bearer <access_token>`)

### Visszaadott Response (JSON - `UserResponse` struktúra)
A válasz tartalmazza a felhasználó alapadatait, valamint a jogosultsági és céges/privát kontextust meghatározó mezőket:

```json
{
  "email": "user@example.com",
  "first_name": "Gábor",
  "last_name": "Kovács",
  "is_active": true,
  "region_code": "HU",
  "id": 123,
  "person_id": 456,
  "role": "USER",
  "subscription_plan": "FREE",
  "scope_level": "individual",
  "scope_id": "123",
  "ui_mode": "personal",
  "active_organization_id": null
}
```

### Kiemelt mezők a jogosultsághoz és céges/privát kontextushoz:
- **`role`**: A felhasználó rendszerszintű jogosultsági köre (pl. `USER`, `ADMIN`, `SUPERADMIN`).
- **`scope_level`**: Meghatározza, hogy a felhasználó milyen szintű adatokhoz fér hozzá (pl. `individual`, `business`).
- **`scope_id`**: A scope-hoz tartozó azonosító (pl. a saját user ID-ja vagy a szervezet ID-ja).
- **`ui_mode`**: Meghatározza az aktuális felületi módot, ami lehet `personal` (privát) vagy `business` (céges nézet).
- **`active_organization_id`**: Ha a felhasználó egy céges környezetbe van belépve, itt jelenik meg az aktív cég (szervezet) azonosítója (int/UUID). Ha privát módban van, az értéke `null`.