# API Kimlik Bilgileri

https://dev.wisecp.com/tr/api-kimlik-bilgileri

API erişim anahtarlarını üreten, sınırlayan ve isteklerini izleyen yedi uç.

## Genel Bakış

Bu yedi uç API'ye **kimin erişebileceğini** yönetir: anahtarları üretir, neye izin verdiklerini belirler, nereden kullanılabileceklerini sınırlar ve kimin neyi çağırdığını gösterir.

Anahtarın kendisi **özet olarak saklanır**. Tam değer üretim yanıtında bir kez görünür; sonrasında hiçbir uç onu geri vermez. Kaybedilen bir anahtar kurtarılmaz, yenisiyle değiştirilir.

İzinler kapsam olarak yazılır: tek bir işlem ya da bir kaynağın tamamı için joker. Bir anahtara yalnız gerçekten ihtiyacı olan kapsamları vermek, bu makaledeki tek asıl tavsiyedir.

Her anahtar onu oluşturan personel hesabına aittir. Bir anahtar, o hesabın panelde yapabildiğinden fazlasını asla yapamaz. Denetim **her istekte** çalışır; bir personelin yetkisi daraltıldığında anahtarları da aynı anda daralır.

## Referans

### Anahtarları Listeleme

get/api/v1/admin/settings/api-credentials

`Settings/GetApiCredentials` admin maskeli döner

Bu API'ye erişim veren anahtarları döndürür.

Sorgu parametreleri 3

pageintVarsayılan 1.

limitintVarsayılan 25, en çok 100.

searchstringAnahtarlarda arar.

Dönen alanlar data[] — 11

idintKimlik bilgisinin kimliği.

namestringAnahtarın adı. Yalnız sizin için; nerede kullanıldığını hatırlamanızı sağlar.

typestringKimin oluşturduğu: personel için `admin`, müşteri için `client`. Müşteri anahtarları müşteri panelinden yönetilir.

ownerobjectAnahtarın ait olduğu hesap; `id` ve `name`. Anahtarın erişebileceklerini bu hesabın yetkileri sınırlar.

token_previewstringAnahtarın maskelenmiş hâli. Tam değer geri **alınamaz**; özet olarak saklanır.

permissionsstring[]İzin verilen kapsamlar. Tek bir işlem ya da bir kaynağın tamamı için joker yazılabilir.

ipsstring[]İzin verilen adresler. Boşsa her yerden kullanılabilir.

rate_limitintBu anahtara özel dakikalık istek sınırı. Sıfır, genel varsayılanı kullanır.

created_atstring | nullOluşturulma zamanı.

updated_atstring | nullSon değişiklik zamanı.

last_accessstring | nullEn son ne zaman kullanıldığı. Boşsa hiç kullanılmamıştır.

Meta 4

totalintToplam anahtar sayısı.

pageintBulunduğunuz sayfa.

limitintSayfa boyutu.

next_pageintSonraki sayfa. Sıfır son sayfada olduğunuz anlamına gelir.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/settings/api-credentials' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/settings/api-credentials', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/settings/api-credentials');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

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

```php
// Hic kullanilmamis anahtarlar temizlik adayidir: son kullanim bos ise kimse dokunmamis demektir.
$keys   = Api::Settings()->GetApiCredentials()['data'];
$unused = array_filter($keys, fn (array $k): bool => $k['last_access'] === null);
```

### Anahtar Oluşturma

post/api/v1/admin/settings/api-credentials

`Settings/CreateApiCredential` admin anahtar bir kez görünür

Yeni bir erişim anahtarı üretir. Tam değer **yalnız bu yanıtta** döner.

Gövde 4

namestringzorunluAnahtarın adı.

permissionsstring[]zorunluİzin verilecek kapsamlar. En az bir tane gerekir; joker bir kaynağın tüm işlemlerini açar.

ipsstring[] | stringİzin verilecek adresler. Dizi ya da satır satır metin olarak verilebilir.

rate_limitintDakikalık istek sınırı. Sıfır genel varsayılana döner.

Dönen alanlar data — 10

idintKimlik bilgisinin kimliği.

namestringAnahtarın adı. Yalnız sizin için; nerede kullanıldığını hatırlamanızı sağlar.

token_previewstringAnahtarın maskelenmiş hâli. Tam değer geri **alınamaz**; özet olarak saklanır.

permissionsstring[]İzin verilen kapsamlar. Tek bir işlem ya da bir kaynağın tamamı için joker yazılabilir.

ipsstring[]İzin verilen adresler. Boşsa her yerden kullanılabilir.

rate_limitintBu anahtara özel dakikalık istek sınırı. Sıfır, genel varsayılanı kullanır.

created_atstring | nullOluşturulma zamanı.

updated_atstring | nullSon değişiklik zamanı.

last_accessstring | nullEn son ne zaman kullanıldığı. Boşsa hiç kullanılmamıştır.

api_keystringAnahtarın tam değeri. Yalnız burada görünür; kaybederseniz yeni bir anahtar üretmekten başka yol yoktur.

Hatalar 4

name_required422Ad boş.

permissions_required422Hiç izin verilmedi.

permissions_exceed_owner422İstenen kapsamların hiçbiri, anahtarın ait olduğu hesabın yetkilerinin kapsamında değil.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X POST 'https://panel.ornek.com/api/v1/admin/settings/api-credentials' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"name":"Integration","permissions":["Clients/*","Services/GetServices"],"ips":[],"rate_limit":300}'
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/settings/api-credentials', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    name: 'Integration',
    permissions: ['Clients/*', 'Services/GetServices'],
    rate_limit: 300,
  }),
});

const body = await res.json();

// Store it now: this is the only time it is shown.
const newKey = body.data.api_key;
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/settings/api-credentials');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'name'        => 'Integration',
        'permissions' => ['Clients/*'],
        'rate_limit'  => 300,
    ]),
]);

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

```php
// Tam anahtar YALNIZ burada doner; simdi saklamazsaniz bir daha okuyamazsiniz.
$cred = Api::Settings()->CreateApiCredential([
    'name'        => 'Integration',
    'permissions' => ['Clients/*'],
])['data'];

$secret = $cred['api_key'] ?? null;   // sonraki her okumada YOK
```

Yanıt 201 422

```json
{
  "data": {
    "id": 13,
    "name": "Integration",
    "token_preview": "wak_a1b2c3d4e••••••••",
    "permissions": ["Clients/*"],
    "ips": [],
    "rate_limit": 300,
    "api_key": "wak_a1b2c3d4e5f6..."
  }
}
```

```json
{
  "error": {
    "code": "permissions_required",
    "message": "At least one permission is required."
  }
}
```

### Anahtar Detayı

get/api/v1/admin/settings/api-credentials/{cid}

`Settings/GetApiCredential` admin

Tek bir anahtarı döndürür. Şema liste öğesiyle aynıdır ve anahtar yine maskelidir.

Dönen alanlar data — 11

idintKimlik bilgisinin kimliği.

namestringAnahtarın adı. Yalnız sizin için; nerede kullanıldığını hatırlamanızı sağlar.

typestringKimin oluşturduğu: personel için `admin`, müşteri için `client`. Müşteri anahtarları müşteri panelinden yönetilir.

ownerobjectAnahtarın ait olduğu hesap; `id` ve `name`. Anahtarın erişebileceklerini bu hesabın yetkileri sınırlar.

token_previewstringAnahtarın maskelenmiş hâli. Tam değer geri **alınamaz**; özet olarak saklanır.

permissionsstring[]İzin verilen kapsamlar. Tek bir işlem ya da bir kaynağın tamamı için joker yazılabilir.

ipsstring[]İzin verilen adresler. Boşsa her yerden kullanılabilir.

rate_limitintBu anahtara özel dakikalık istek sınırı. Sıfır, genel varsayılanı kullanır.

created_atstring | nullOluşturulma zamanı.

updated_atstring | nullSon değişiklik zamanı.

last_accessstring | nullEn son ne zaman kullanıldığı. Boşsa hiç kullanılmamıştır.

Hatalar 2

not_found404Kimlik bilgisi bulunamadı.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/settings/api-credentials/12' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/settings/api-credentials/12', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/settings/api-credentials/12');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

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

```php
// Detay da tam anahtari VERMEZ: kaybedilen bir anahtar kurtarilamaz, yenisi uretilir.
$cred = Api::Settings()->GetApiCredential(['cid' => 12])['data'];
```

### Anahtarı Güncelleme

patch/api/v1/admin/settings/api-credentials/{cid}

`Settings/UpdateApiCredential` admin izinler bütün yazılır

Gönderdiğiniz alanları uygular, gerisine dokunmaz: ad, izinler, adres listesi ve istek sınırı. Anahtarın kendisi değişmez.

Gövde 4

namestringAnahtarın adı. Göndermezseniz kayıtlı ad kalır.

permissionsstring[]İzin verilecek kapsamlar. Göndermezseniz kayıtlı liste kalır; gönderdiğinizde set bütün olarak değişir ve boş liste hata verir. Joker bir kaynağın tüm işlemlerini açar.

ipsstring[] | stringİzin verilecek adresler. Dizi ya da satır satır metin olarak verilebilir.

rate_limitintDakikalık istek sınırı. Sıfır genel varsayılana döner.

Dönen alanlar data — 11

dataobjectGüncel kimlik bilgisi. Listedeki öğeyle aynı şekildedir; anahtarın kendisi değişmez ve maskeli kalır.

Hatalar 7

not_found404Kimlik bilgisi bulunamadı.

not_credential_owner403Anahtar başka bir personel hesabına ait. Kök yetki grubuna ait bir anahtar tüm kimlik bilgilerine erişir.

client_credential422Anahtar bir müşteriye ait ve müşteri panelinden yönetilir.

name_required422Gönderilen ad boş.

permissions_required422Gönderilen izin listesi boş.

permissions_exceed_owner422İstenen kapsamların hiçbiri, anahtarın ait olduğu hesabın yetkilerinin kapsamında değil.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X PATCH 'https://panel.ornek.com/api/v1/admin/settings/api-credentials/12' \
  -H "Authorization: Bearer $API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"permissions":["Clients/*","Invoices/*"],"ips":["203.0.113.10"]}'
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/settings/api-credentials/12', {
  method: 'PATCH',
  headers: {
    Authorization: `Bearer ${apiKey}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    permissions: ['Clients/*', 'Invoices/*'],
    ips: ['203.0.113.10'],
  }),
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/settings/api-credentials/12');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'PATCH',
    CURLOPT_HTTPHEADER     => [
        'Authorization: Bearer ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode([
        'permissions' => ['Clients/*', 'Invoices/*'],
        'ips'         => ['203.0.113.10'],
    ]),
]);

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

```php
// Izin EKLEMEK icin mevcut listeyi de gonderin: gonderdiginiz set eskisinin yerine gecer.
$cred  = Api::Settings()->GetApiCredential(['cid' => 12])['data'];
$scope = $cred['permissions'];

$scope[] = 'Invoices/*';

Api::Settings()->UpdateApiCredential(['cid' => 12, 'permissions' => $scope]);
```

### Anahtarı Silme

delete/api/v1/admin/settings/api-credentials/{cid}

`Settings/DeleteApiCredential` admin erişim anında kesilir

Anahtarı iptal eder. O anahtarı kullanan her istek anında reddedilmeye başlar.

Dönen alanlar data — 2

deletedboolSilme başarılı mı.

idintSilinen anahtarın kimliği.

Hatalar 4

not_found404Kimlik bilgisi bulunamadı.

not_credential_owner403Anahtar başka bir personel hesabına ait. Kök yetki grubuna ait bir anahtar tüm kimlik bilgilerine erişir.

client_credential422Anahtar bir müşteriye ait ve müşteri panelinden yönetilir.

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X DELETE 'https://panel.ornek.com/api/v1/admin/settings/api-credentials/12' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/settings/api-credentials/12', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/settings/api-credentials/12');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

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

```php
// Kendi anahtarinizi silmek o anki oturumun ERISIMINI de keser; kilitlenmemek icin dikkat.
Api::Settings()->DeleteApiCredential(['cid' => 12]);
```

### İstek Kayıtlarını Listeleme

get/api/v1/admin/settings/api-logs

`Settings/GetApiLogs` admin sayfalı

API'ye gelen isteklerin kaydını döndürür.

Sorgu parametreleri 3

pageintVarsayılan 1.

limitintVarsayılan 25, en çok 100.

searchstringKayıtlarda arar.

Dönen alanlar data[] — 6

idintKaydın kimliği.

credentialobjectİsteği yapan anahtar: kimliği ve adı.

methodstringİstek yöntemi.

actionstringÇağrılan işlem.

ipstringİsteğin geldiği adres.

created_atstring | nullİsteğin zamanı.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl 'https://panel.ornek.com/api/v1/admin/settings/api-logs' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res  = await fetch('https://panel.ornek.com/api/v1/admin/settings/api-logs', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/settings/api-logs');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

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

```php
// Kayit gonderilen VERIYI tutmaz: hangi anahtarin neyi cagirdigini gorursunuz, ne gonderdigini degil.
$logs = Api::Settings()->GetApiLogs()['data'];
```

### İstek Kayıtlarını Temizleme

delete/api/v1/admin/settings/api-logs

`Settings/ClearApiLogs` admin tarih almaz

API istek kayıtlarının tamamını siler.

Dönen alanlar data — 1

clearedboolTemizlik çalıştı mı.

Hatalar 1

insufficient_scope403Anahtar gerekli kapsamı taşımıyor.

İstek cURL JavaScript PHP (HTTP) PHP (Dahili)

```bash
curl -X DELETE 'https://panel.ornek.com/api/v1/admin/settings/api-logs' \
  -H "Authorization: Bearer $API_KEY"
```

```javascript
const res = await fetch('https://panel.ornek.com/api/v1/admin/settings/api-logs', {
  method: 'DELETE',
  headers: { Authorization: `Bearer ${apiKey}` },
});

const body = await res.json();
```

```php
$ch = curl_init('https://panel.ornek.com/api/v1/admin/settings/api-logs');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_CUSTOMREQUEST  => 'DELETE',
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . $apiKey],
]);

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

```php
// Bu uc TARIH almaz: kayitlarin tamami gider, secmeli temizlik yoktur.
Api::Settings()->ClearApiLogs();
```

## Tuzaklar

> **Anahtar sahibini izler**
> 
> Kapsamlar her istekte sahibin yetkileriyle kesiştirilir. O personel hesabından bir izin alındığında anahtar da onu kaybeder; düzenleme gerekmez. Hesap silinir ya da engellenirse anahtar çalışmayı bırakır ve `owner_inactive` döner. Sahibinin hâlâ yapabildiği hiçbir şey kalmayan anahtar `owner_scope_revoked` döner.

> **Anahtar bir kez görünür**
> 
> Tam anahtar **yalnız oluşturma yanıtında** döner. Listeleme ve detay uçları onu maskeli verir; özet olarak saklandığı için sunucu bile ham değeri bilmez. O yanıtı kaçırırsanız yapılabilecek tek şey anahtarı silip yenisini üretmektir.

> **İzin listesi bütün olarak yazılır**
> 
> Güncellemede gönderdiğiniz kapsam listesi eskisinin **yerine geçer**. Tek bir izin eklemek için önce mevcut listeyi okuyup üzerine eklemeniz gerekir; yoksa anahtar sessizce yetkisiz kalır ve entegrasyonunuz çalışmayı bırakır.

> **Kendi anahtarınızı silmek sizi de keser**
> 
> Silme anında etkilidir ve **o anda kullandığınız anahtar** da buna dahildir. Bir entegrasyonun anahtarını temizlerken hangi anahtarla istek yaptığınıza dikkat edin; kendinizi kilitlerseniz panelden yeni bir anahtar üretmekten başka yol kalmaz.

> **Boş adres listesi her yeri açar**
> 
> Adres listesi boş bırakılan bir anahtar **dünyanın her yerinden** kullanılabilir. Sunucudan sunucuya çalışan bir entegrasyonda o sunucunun adresini yazmak, anahtar sızsa bile kullanılmasını engeller; bu, kapsam daraltmanın ardından en ucuz korumadır.

> **İstek kaydı gönderilen veriyi tutmaz**
> 
> Kayıt hangi anahtarın hangi işlemi hangi adresten çağırdığını gösterir; **gövdeyi ya da yanıtı saklamaz**. Bir isteğin neyi değiştirdiğini araştırıyorsanız burası yetmez, ilgili kaydın kendi geçmişine bakmanız gerekir. Temizlik ucu de tarih almaz: hepsi ya da hiçbiri.

## İlgili Makaleler

- [Güvenlik Ayarları](https://dev.wisecp.com/tr/guvenlik-ayarlari)
- [Site Ayarları](https://dev.wisecp.com/tr/site-ayarlari)