# API Kimlik Doğrulama ve İzinler

https://dev.wisecp.com/tr/api-kimlik-dogrulama-ve-izinler

Anahtar nasıl üretilir, istekte nasıl taşınır ve izinleri nereye erişebileceğine nasıl karar verir.

## Genel Bakış

Kimlik isteyen her çağrı yalnızca bir API anahtarı taşır. Oturum ve çerez yok, dolayısıyla çağrı bir sunucudan da dizüstünden de tarayıcı sekmesinden de aynı davranır.

Anahtar üç şey tutar: ait olduğu adres, kendisine verilen izin listesi ve dakika başına istek bütçesi. Üçü her istekte bu sırayla kontrol edilir; hayır diyen ilki çağrıyı bitirir.

Anahtarın kendisi saklanmaz. Kurulumda duran şey, onun özeti ve gösterim için ilk birkaç karakteridir. Kaybolan bir anahtar panelden geri alınamaz, yalnızca yenisiyle değiştirilir.

## Ön Koşullar

- Yönetim anahtarı için panel erişimi, müşteri anahtarı için bir müşteri hesabı.
- Anahtarı saklayacağınız, kaynak kod deponuz olmayan bir yer.

## Adım Adım

### Anahtar Üretin

1. Yönetim adresi için panelde **Ayarlar → API Kimlik Bilgileri** ekranını açın ve bir kimlik bilgisi oluşturun.
2. Müşteri adresi için müşteri kendi hesabındaki **API Kimlik Bilgileri** sayfasından, `/api-credentials` adresinde oluşturur.
3. Anahtarı onay ekranından kopyalayın. Bir kez gösterilir, bir daha gösterilmez.

### İzinleri Verin

1. Anahtarın ihtiyaç duyduğu eylemleri işaretleyin. Her onay kutusu bir `Grup/Eylem` çiftidir; ucun dokümanındaki adla aynıdır.
2. İşi gören en dar kümeyi verin. Yalnızca fatura okuyan bir anahtar müşterilerinize karşı kullanılamaz.
3. İsterseniz o anahtara özel dakikalık bütçeyi yükseltin ya da düşürün; boş bırakmak kurulum varsayılanı demektir.

### Gönderin ve Doğrulayın

1. Anahtarı `Authorization: Bearer` başlığına koyun; istemciniz bunu kuramıyorsa `X-Api-Key` başlığını kullanın.
2. Anahtarı ürettiğiniz adreste `whoami` ucunu çağırın. Anahtarın kimliğini, izinlerini ve müşteri adresinde arkasındaki hesabı döndürür.
3. Buradaki bir `403` anahtarın gerçek ama diğer adrese ait olduğu anlamına gelir. Anahtarı değil adresi kontrol edin.

## Referans

- **wak_ + 32 karakter**: `/api/v1/admin` adresine erişir. Personel üretir, izinle sınırlanır, tek bir müşteriye bağlı değildir.
- **wck_ + 32 karakter**: `/api/v1/client` adresine erişir. Onu oluşturan hesaba bağlıdır; yaptığı her sorgu o hesaba göre süzülür.
- **Clients/GetClients**: Tek bir eylem. Güvenli varsayılan ve her ucun dokümanında adı geçen izin.
- **Clients/***: O gruptaki her eylem, sonraki sürümlerde eklenenler dahil. Pratik, ama göründüğünden geniş.
- *****: Adresin tamamı. Yalnızca tam denetiminizde olan ve hızlıca değiştirebileceğiniz bir anahtara verin.

Retler bilerek birbirinden ayrıdır; böylece çalışmayan bir entegrasyon üç kontrolden hangisinin onu durdurduğunu size söyler.

- **401 missing_token**: Hiç anahtar gelmedi. Genellikle istemcinin düşürdüğü bir başlıktır, izin sorunu değil.
- **403 audience_mismatch**: Gerçek bir anahtar, yanlış adreste.
- **403 insufficient_scope**: Anahtar geçerli ve uç var, ama o eylem verilmemiş. Mesaj eksik izni adıyla söyler.
- **429 rate_limited**: Dakikalık bütçe tükendi. `Retry-After` ne kadar bekleneceğini söyler.

## Örnek

```bash
KEY=$(cat ~/.config/wisecp.key)

curl -H "Authorization: Bearer $KEY" \
     'https://panel.example.com/api/v1/admin/whoami'
# {"data":{"id":7,"type":"admin","name":"Fatura senkronu","permissions":["Invoices/*","Clients/GetClients"]}}
```

```php
$ch = curl_init('https://panel.example.com/api/v1/admin/whoami');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('WISECP_API_KEY')],
]);

$body = json_decode(curl_exec($ch), true);
curl_close($ch);

$izinler = $body['data']['permissions'] ?? [];
```

## Tuzaklar

> **Anahtar bir kez gösterilir**
> 
> Yalnızca özeti saklanır; onu sonradan gösteren bir ekran ve geri getirebilecek bir destek talebi yoktur. Kaybolursa kimlik bilgisini yenileyin ve onu kullanan her yeri güncelleyin. Yenilemeyi küçük bir kesinti gibi görüp planlayın.

> **429 yanıtını yok saymak, ona uymaktan pahalıdır**
> 
> Bütçe sabit bir dakikalık penceredir: kurulum aksini söylemedikçe yönetim anahtarı için 120, müşteri anahtarı için 60 istek. Bütçesini fazlasıyla aşarak zorlamayı sürdüren bir çağıran, reddedilmekle kalmaz, bir süre kilitlenir. `X-RateLimit-Remaining` değerini okuyun ve `Retry-After` kadar bekleyin.

> **Üst üste hatalı kimlik adresinizi kilitler**
> 
> Başarısız kimlik doğrulama adres başına sayılır; kısa bir pencerede yeterince başarısızlık geçici bir engel ve `too_many_auth_failures` yanıtı getirir. Yanlış anahtarın etrafındaki bir yeniden deneme döngüsü bunu sizden önce bulur; `401` aldığınızda yeniden denemek yerine açıkça hata verin.

## İlgili Makaleler

- [WISECP API'si](https://dev.wisecp.com/tr/wisecp-apisi)
- [İstek ve Yanıt Biçimi](https://dev.wisecp.com/tr/istek-ve-yanit-bicimi)
- [API Kaynakları](https://dev.wisecp.com/tr/api-kaynaklari)
- [Müşteri API'sine Giriş](https://dev.wisecp.com/tr/musteri-api-giris)