API Kimlik Bilgileri

1.7k görüntülenme Markdown

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 'https://panel.ornek.com/api/v1/admin/settings/api-credentials' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.ornek.com/api/v1/admin/settings/api-credentials', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$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);
// 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 -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}'
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;
$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);
// 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 
{
  "data": {
    "id": 13,
    "name": "Integration",
    "token_preview": "wak_a1b2c3d4e••••••••",
    "permissions": ["Clients/*"],
    "ips": [],
    "rate_limit": 300,
    "api_key": "wak_a1b2c3d4e5f6..."
  }
}
{
  "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 'https://panel.ornek.com/api/v1/admin/settings/api-credentials/12' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.ornek.com/api/v1/admin/settings/api-credentials/12', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$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);
// 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 -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"]}'
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();
$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);
// 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 -X DELETE 'https://panel.ornek.com/api/v1/admin/settings/api-credentials/12' \
  -H "Authorization: Bearer $API_KEY"
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();
$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);
// 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 'https://panel.ornek.com/api/v1/admin/settings/api-logs' \
  -H "Authorization: Bearer $API_KEY"
const res  = await fetch('https://panel.ornek.com/api/v1/admin/settings/api-logs', {
  headers: { Authorization: `Bearer ${apiKey}` },
});
const body = await res.json();
$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);
// 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 -X DELETE 'https://panel.ornek.com/api/v1/admin/settings/api-logs' \
  -H "Authorization: Bearer $API_KEY"
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();
$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);
// 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.

Faydalı oldu mu?

Geri bildiriminiz için teşekkürler!

Hâlâ Yardıma mı İhtiyacınız Var?

Yukarıda bulamadığınız her şey için destek ekibimiz her zaman yanınızda.

Bize Ulaşın Destek Talebi Oluştur

Oturumunuzu açık tutmak, dil ve para birimi tercihinizi hatırlamak ve siteyi geliştirmek için çerez kullanıyoruz. Çerez Politikası