> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flextell.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hesap API

> Oturum açmış kullanıcının kendi hesabını yönetmek için endpoint'ler: profil, şifre, 2FA, oturum ve yetki sorgulama.

<Note>
  Bu gruptaki endpoint'ler **tenant bağımsızdır** — oturum açmış kullanıcının kendi hesabını yönetmek için kullanılır. `/account/roles` endpoint'i tek istisnadır: `X-Tenant` header'ı **zorunludur**.
</Note>

## Endpoint özeti

| Metot  | Endpoint                                               | Açıklama                                  | Throttle            |
| ------ | ------------------------------------------------------ | ----------------------------------------- | ------------------- |
| `GET`  | `/api/v1/account`                                      | Hesap bilgilerini getirir                 | —                   |
| `PUT`  | `/api/v1/account`                                      | Hesap bilgilerini günceller               | —                   |
| `PUT`  | `/api/v1/account/password`                             | Şifre günceller                           | `account:sensitive` |
| `GET`  | `/api/v1/account/tenants`                              | Bağlı tenant listesini getirir            | —                   |
| `GET`  | `/api/v1/account/roles`                                | Aktif tenant'taki rol ve izinleri getirir | —                   |
| `GET`  | `/api/v1/account/two-factor`                           | 2FA durumunu getirir                      | —                   |
| `POST` | `/api/v1/account/two-factor`                           | 2FA'yı etkinleştirir                      | `account:sensitive` |
| `POST` | `/api/v1/account/two-factor/confirm`                   | 2FA'yı TOTP koduyla onaylar               | `account:2fa`       |
| `POST` | `/api/v1/account/two-factor/disable`                   | 2FA'yı devre dışı bırakır                 | `account:sensitive` |
| `POST` | `/api/v1/account/two-factor/recovery-codes/regenerate` | Recovery code'ları yeniler                | `account:sensitive` |
| `GET`  | `/api/v1/account/browser-sessions`                     | Aktif oturumları listeler                 | —                   |
| `POST` | `/api/v1/account/browser-sessions/logout`              | Diğer oturumları kapatır                  | `account:sensitive` |

<Tip>
  Tüm parametreler, alanlar ve örnek istek/yanıtlar için **[API Referansı](/api-reference)** sekmesine bakın.
</Tip>

## Hesap kavramı ve akış

Sisteme başarılı bir şekilde giriş yapıp bir Access Token (Bearer token) aldığınızda **ilk yapmanız gereken** `/api/v1/account` endpoint'ine istek atarak kullanıcının kim olduğunu öğrenmektir.

Sistemimiz Multi-Tenant (çoklu kiracı / klinik) yapısında olduğu için bir kullanıcı birden fazla kliniğe üye olabilir. Doğru verilerle çalışabilmek için uygulamanızın aşağıdaki akışı izlemesi önerilir:

<Steps>
  <Step title="Profili ve klinikleri al">
    `GET /account` ile kullanıcının profili ve bağlı olduğu klinikler (`tenants`) alınır.
  </Step>

  <Step title="Klinik seçtir">
    Kullanıcıya bir klinik (tenant) seçtirilir; tek klinik varsa otomatik seçilir.
  </Step>

  <Step title="X-Tenant header'ı olarak gönder">
    Seçilen kliniğin ID'si uygulamanın hafızasına alınır ve bundan sonraki tüm veri isteklerinde `X-Tenant: {id}` header'ı olarak gönderilir.
  </Step>

  <Step title="Yetkileri kontrol et">
    UI/menü görünürlüğünü ayarlamak için `X-Tenant` header'ı ile birlikte `GET /account/roles` isteği atılır ve kullanıcının o klinikte neleri görmeye yetkili olduğu öğrenilir.
  </Step>
</Steps>

## Profil güncelleme (`PUT /account`)

Tüm alanlar isteğe bağlıdır; sadece gönderilen alanlar güncellenir.

| Alan         | Tip          | Açıklama                                   |
| ------------ | ------------ | ------------------------------------------ |
| `name`       | string       | Maks. 255 karakter                         |
| `email`      | string       | E-posta formatı, sistemde benzersiz olmalı |
| `avatar_url` | string\|null | Geçerli URL formatı                        |

## Şifre değiştirme (`PUT /account/password`)

<Note>
  Şifre değiştirme `account:sensitive` throttle kapsamındadır. İşlem başarılı olursa aktivite logu yazılır.
</Note>

| Alan                    | Tip    | Zorunlu | Açıklama                     |
| ----------------------- | ------ | ------- | ---------------------------- |
| `current_password`      | string | evet    | Mevcut şifre                 |
| `password`              | string | evet    | Yeni şifre (min. 8 karakter) |
| `password_confirmation` | string | evet    | Yeni şifre tekrarı           |

## Roller ve izinler (`GET /account/roles`)

<Warning>
  Bu istekte `X-Tenant` header'ını göndermek **zorunludur**. Kullanıcının belirtilen tenant'a erişimi yoksa `403` döner.
</Warning>

Kullanıcının, `X-Tenant` header'ında belirttiği klinik içerisinde sahip olduğu rolleri ve ince yetkileri (`permissions`) liste olarak döndürür.

```json theme={null}
{
  "roles": ["doctor", "manager"],
  "permissions": [
    "ViewAny:Customer",
    "Create:Appointment",
    "View:ChatLogPage"
  ]
}
```

Bu endpoint **veri güvenliği sağlamaz** — veri güvenliği backend tarafından korunur. Amacı frontend uygulamanızın arayüzünü (UI) şekillendirmektir. Örneğin:

* `permissions` listesinde `ViewAny:Customer` yoksa sol menüdeki **Hastalar** sekmesini gizlemelisiniz.
* `Create:Appointment` yoksa takvim ekranındaki **Yeni Randevu Ekle** butonunu gizlemelisiniz.

## İki Faktörlü Doğrulama (2FA)

### 2FA Durumu (`GET /account/two-factor`)

Kullanıcının 2FA etkin ve onaylı olup olmadığını döndürür.

```json theme={null}
{
  "is_enabled": false,
  "is_confirmed": false
}
```

### 2FA Etkinleştirme (`POST /account/two-factor`)

<Warning>
  `recovery_codes` **yalnızca bu yanıtta döner** — güvenli bir yerde saklanmalıdır. Kaybolursa `/regenerate` endpoint'i ile yenilenir.
</Warning>

<Note>
  `current_password` alanı zorunludur. İşlem başarılı olursa aktivite logu yazılır.
</Note>

Başarılı yanıt `qr_code_url` (TOTP URI) ve tek seferlik `recovery_codes` listesi içerir. Etkinleştirme sonrası 2FA `is_confirmed: false` durumundadır — `/confirm` endpoint'i ile onaylanması gerekir.

### 2FA Onaylama (`POST /account/two-factor/confirm`)

<Note>
  `account:2fa` throttle kapsamındadır (şifre throttle'ından daha kısıtlı). İşlem başarılı olursa aktivite logu yazılır.
</Note>

| Alan   | Tip    | Zorunlu | Açıklama                                      |
| ------ | ------ | ------- | --------------------------------------------- |
| `code` | string | evet    | Authenticator uygulamasından alınan TOTP kodu |

2FA etkin değilse veya kod geçersizse `422` döner. Başarılı yanıt `is_confirmed: true` içerir.

### 2FA Devre Dışı Bırakma (`POST /account/two-factor/disable`)

<Note>
  `current_password` alanı zorunludur. İşlem başarılı olursa aktivite logu yazılır.
</Note>

### Recovery Code Yenileme (`POST /account/two-factor/recovery-codes/regenerate`)

<Warning>
  **Eski recovery code'lar geçersiz hale gelir.** Yeni kodlar yalnızca bu yanıtta döner; güvenli bir yerde saklanmalıdır.
</Warning>

<Note>
  `current_password` alanı zorunludur. 2FA etkin değilse `422` döner. İşlem başarılı olursa aktivite logu yazılır.
</Note>

## Tarayıcı Oturumları

### Oturum Listesi (`GET /account/browser-sessions`)

Aktif tüm oturumları listeler. Her oturum için `ip_address`, `user_agent`, `last_active_at`, `is_current_device` ve cihaz bilgisi (`browser`, `platform`, `desktop`, `mobile`, `tablet`) döner.

`is_current_device: true` olan oturum şu an kullanılan cihazdır.

### Diğer Oturumları Kapatma (`POST /account/browser-sessions/logout`)

<Note>
  `current_password` alanı zorunludur. **Mevcut oturum korunur** — sadece diğer tüm oturumlar silinir.
</Note>

<Warning>
  İstek bir Cache lock ile korunur. Lock alınamazsa (eş zamanlı istek) `409 Conflict` döner.
</Warning>

İşlem başarılı olursa silinen oturum sayısıyla birlikte aktivite logu yazılır.

## Yetkilendirme

### Token scope'ları (Passport)

| İşlem                 | Scope           |
| --------------------- | --------------- |
| Okuma (`GET`)         | `account:read`  |
| Yazma (`PUT`, `POST`) | `account:write` |