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

# Kimlik doğrulama

> API’yi Basic Auth ile koruyun, ardından her WhatsApp hesabını QR kodu, eşleştirme kodu veya geçiş anahtarıyla eşleştirin.

GOWA’da iki ayrı kimlik doğrulama türü vardır:

1. **API erişimi**: GOWA’yı kimlerin çağırabileceğini belirler. HTTP Basic Auth kullanılır.
2. **WhatsApp eşleştirme**: WhatsApp Web’i bağlarken olduğu gibi, bir WhatsApp hesabını cihaz yuvasına bağlamaktır.

## API erişimi: Basic Auth

Basic Auth, API için tek kimlik doğrulama yöntemidir. REST çağrıları için API anahtarı veya JWT yoktur.

Bir veya daha fazla `user:password` çiftini virgülle ayırarak ayarlayın:

```bash theme={null}
# environment
APP_BASIC_AUTH=admin:changeme,ops:another-secret
# or flag
./whatsapp rest --basic-auth=admin:changeme,ops:another-secret
```

Her girişte boş olmayan bir kullanıcı adı ve parola bulunmalıdır. Varsayılan dinleyici `APP_HOST=0.0.0.0`, eksiksiz kimlik bilgileri olmadan başlamayı reddeder. Kimlik doğrulamasız yerel geliştirme için `APP_HOST=127.0.0.1` adresine bağlayın.

Bir ters vekil her çağrıyı yapanın kimliğini doğruluyorsa `APP_ALLOW_UNAUTHENTICATED=true` veya `--allow-unauthenticated=true`, geri döngü dışı bir dinleyicinin Basic Auth olmadan çalışmasına açıkça izin verir. Bu dinleyiciye doğrudan erişimi kısıtlayın.

Her istekte kimlik bilgilerini gönderin:

```bash theme={null}
curl -u admin:changeme http://localhost:3000/app/info
# same as
curl -H "Authorization: Basic YWRtaW46Y2hhbmdlbWU=" http://localhost:3000/app/info
```

Eksik veya yanlış kimlik bilgileri `401 Unauthorized` yanıtına yol açar.

### Basic Auth ile korunmayanlar

| Yol | Nedeni |
| - | - |
| `GET /health` | Canlılık yoklaması. `APP_BASE_PATH` dikkate alınmadan her zaman köktedir. |
| `POST /chatwoot/webhook`, `POST /chatwoot/webhook/{device_id}` | Chatwoot tarafından çağrılır. Yalnızca `CHATWOOT_ENABLED=true` olduğunda kaydedilir ve bunun yerine `CHATWOOT_WEBHOOK_SECRET` ile korunur. [Chatwoot’a](https://gowa-docs.mintlify.site/tr/integrations/chatwoot.md) bakın. |
| MCP OAuth keşfi ve `/oauth/*` uç noktaları | Yalnızca `MCP_OAUTH_ENABLED=true` olduğunda. [MCP sunucusuna](https://gowa-docs.mintlify.site/tr/integrations/mcp.md) bakın. |
| `GET /statics/*` | QR görselleri, yüklemeler ve indirilen medya. Basic Auth’tan önce sunulur. Bir dosyanın URL’sini bilen herkes dosyayı alabilir. Görsel yollarında yalnızca doğrulanmış JPEG, PNG, GIF ve WebP dosyaları satır içinde görüntülenir. Diğer dosyalar, etkin olmayan bir içerik türü ve `X-Content-Type-Options: nosniff` ile ek olarak indirilir. Gerektiğinde dosya erişimini vekilde kısıtlayın. |

`/` yolundaki kontrol paneli, `/mcp` ve `/ws` dahil diğer her şey, yapılandırıldığında Basic Auth gerektirir.

### WebSocket

Tarayıcılar WebSocket bağlantılarında başlık ayarlayamadığından `/ws`, kimlik bilgisini sorgu dizesinden alır:

```text theme={null}
ws://localhost:3000/ws?device_id=my-device&authorization=YWRtaW46Y2hhbmdlbWU=
```

`authorization`, `base64(user:password)` biçimindedir. TLS (`wss://`) kullanın ve vekil günlüklerinde sorgu dizesini gizleyin. WebSocket, tarayıcı kaynağını durum değiştiren HTTP isteklerinde kullanılan güvenilen kaynaklarla karşılaştırır. Mevcut WebSocket merkezi, olayları bağlı tüm soketlere yayınlar. `device_id` sorgusu bağlantının cihaz bağlamını seçer ancak olay iletimini yalıtmaz. Kontrol paneli görünümünü filtrelemek için olayın cihaz tanımlayıcılarını kullanın ve API erişimini yalnızca tüm cihazlara erişimine güvenilen çağrıcılara verin.

Olay kodları, yükler ve bir istemci örneği için [WebSocket başvurusuna](https://gowa-docs.mintlify.site/tr/api-reference/websocket.md) bakın.

### CORS

CORS varsayılan olarak tüm kaynaklara izin verir. `APP_CORS_ALLOWED_ORIGINS=https://ui.example.com` ile kısıtlayın (virgülle ayrılmış). İzin verilen istek başlıkları `Origin`, `Content-Type`, `Accept`, `Authorization` ve `X-Device-Id` şeklindedir.

CORS ile tarayıcı kaynak denetimleri ayrıdır. Joker karakterli bir CORS kaynağı, durum değiştiren isteklere veya WebSocket bağlantılarına izin vermez. GOWA, isteğin kendi ana makinesine, belirli CORS kaynaklarına, `APP_TRUSTED_ORIGINS` değerlerine ve OAuth sağlayıcısı ile Chatwoot geri çağrı URL’si için yapılandırılan kaynaklara güvenir. Ayrı bir kontrol paneli için tam kaynağını yapılandırın:

```env theme={null}
APP_CORS_ALLOWED_ORIGINS=https://ui.example.com
APP_TRUSTED_ORIGINS=https://ui.example.com
```

Güvenilmeyen bir tarayıcı durum değişikliği isteği `403 CROSS_SITE_REQUEST_BLOCKED` döndürür. Bu, oturum açan, oturumu kapatan, yeniden bağlanan veya davet bağlantısını sıfırlayan GET yollarını da kapsar. Tarayıcı kaynak başlıkları göndermeyen curl gibi istemciler çalışmaya devam eder.

`null` kaynağına asla güvenilmez. `gowa-ui.html` dosyasını `file://` URL’si olarak açmak yerine HTTP veya HTTPS üzerinden sunun. Bir ters vekilin arkasında `Host` başlığını koruyun, güvenilen vekilleri `X-Forwarded-Host` ile yapılandırın veya genel erişime açık kaynağı `APP_TRUSTED_ORIGINS` içinde listeleyin.

## WhatsApp eşleştirme

Her WhatsApp hesabı bir **cihaz yuvasında** bulunur. Önce yuvayı oluşturun, ardından eşleştirin. `/devices/{device_id}` altındaki yollar, cihazı yoldan alır. Eşdeğer `/app/*` yolları `X-Device-Id` başlığını kullanır.

```bash theme={null}
curl -u admin:changeme -X POST http://localhost:3000/devices \
  -H "Content-Type: application/json" -d '{"device_id": "sales"}'
```

### QR kodu

```bash theme={null}
curl -u admin:changeme http://localhost:3000/devices/sales/login
```

```json theme={null}
{
  "code": "SUCCESS",
  "message": "Login success",
  "results": {
    "device_id": "sales",
    "qr_link": "http://localhost:3000/statics/qrcode/scan-qr-b0b7bb43-....png",
    "qr_duration": 30
  }
}
```

`qr_link` adresini açın ve telefondan tarayın: **Ayarlar → Bağlı cihazlar → Cihaz bağla**. `qr_duration` saniye sonra yeni bir kod isteyin. `/` yolundaki kontrol paneli QR kodunu doğrudan gösterir ve WebSocket üzerinden canlı güncellenir.

### Eşleştirme kodu

```bash theme={null}
curl -u admin:changeme -X POST \
  "http://localhost:3000/devices/sales/login/code?phone=628123456789"
```

Yanıtta 8 karakterli `results.pair_code` kodu bulunur. Telefonda **Bunun yerine telefon numarasıyla bağla** seçeneğini seçip kodu yazın. `phone`, bağlanan hesabın ülke kodunu içeren numarası olmalıdır.

### Geçiş anahtarı

QR ile oturum açarken telefon geçiş anahtarı doğrulaması isterse GOWA bir WebAuthn doğrulama isteği saklar ve WebSocket üzerinden `PASSKEY_REQUEST` yayınlar. Kontrol paneli bu akışı yönetir. Kendiniz yönetmek için:

1. `GET /app/passkey`, bekleyen doğrulama isteğini döndürür.
2. `POST /app/passkey/response`, WebAuthn doğrulama beyanını gönderir (`PublicKeyCredential.toJSON()` biçiminde).
3. `PASSKEY_CONFIRMATION` olayını bekleyin. `result.skip_handoff_ux` doğru olduğunda etkin QR akışı onayı otomatik gönderir. Aksi halde `result.code` değerini telefondaki kodla karşılaştırın, ardından `POST /app/passkey/confirm` çağrısı yapın.

Üç çağrının tamamında `X-Device-Id` gönderin.

### Sonucu kontrol edin

```bash theme={null}
curl -u admin:changeme http://localhost:3000/devices/sales/status
```

Hesap bağlandığında `results.is_connected` ve `results.is_logged_in` değerlerinin ikisi de `true` olur. Oturumlar `storages/` içinde kalıcı olarak saklanır; bu nedenle yeniden başlatmalarda tekrar eşleştirme gerekmez.

## Oturumu kapatma ve kaldırma

| İşlem | Uç nokta | Etkisi |
| - | - | - |
| Oturumu kapat | `POST /devices/{device_id}/logout` veya `GET /app/logout` | Hesabın WhatsApp bağlantısını kaldırır ve oturumunu temizler. Yuva kalır; böylece aynı kimlikle yeniden eşleştirebilirsiniz. |
| Yeniden bağlan | `POST /devices/{device_id}/reconnect` veya `GET /app/reconnect` | Yeniden eşleştirmeden WhatsApp bağlantısını tekrar açar. |
| Kaldır | `DELETE /devices/{device_id}` | Oturumu kapatır, ardından yuvayı oturumu ve sohbet verileriyle birlikte siler. |

Telefondan bağlantısı kaldırılan bir hesabın (Bağlı cihazlar → Çıkış yap) oturumu da aynı şekilde kapatılır: yuva kalır ve yeniden eşleştirilmesi gerekir.

## Güvenlik kontrol listesi

* Ağdan erişilebilen her kurulumda `APP_BASIC_AUTH` değerini güçlü parolalarla ayarlayın.
* TLS’i bir ters vekilde sonlandırın; Basic Auth kimlik bilgileri yalnızca base64 ile kodlanır.
* Bir tarayıcı arayüzü API’yi çağırdığında `APP_CORS_ALLOWED_ORIGINS` değerini kısıtlayın.
* Kalıcı bir `WHATSAPP_WEBHOOK_SECRET` anahtarını `openssl rand -hex 32` ile oluşturun. Boş veya yayımlanmış örnek gizli anahtarlar, her süreç için rastgele üretilen ve yeniden başlatıldığında değişen bir anahtarla değiştirilir.
* `storages/` dizinini hassas veri olarak değerlendirin. Bağlı her hesabın oturum anahtarlarını içerir. Yeni SQLite dosyaları yalnızca sahibine erişim veren izinler kullanır; bunlar için oluşturulan dizinlerde `0700` kullanılır. Yedekleri de aynı özenle koruyun.


## Related topics

- [API Referansı](https://gowa-docs.mintlify.site/tr/api-reference/introduction.md)
- [Üretim Ortamı İçin En İyi Uygulamalar](https://gowa-docs.mintlify.site/tr/advanced/best-practices.md)
- [Hata İşleme](https://gowa-docs.mintlify.site/tr/advanced/error-handling.md)
- [MCP Sunucusu](https://gowa-docs.mintlify.site/tr/integrations/mcp.md)
- [API Kimlik Doğrulaması](https://gowa-docs.mintlify.site/tr/api-reference/authentication.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.