71 lines
2.9 KiB
Markdown
71 lines
2.9 KiB
Markdown
# 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`.
|