Kimlik doğrulama | Veri Merkezi API

Veri Merkezi API'si her istekte bir API anahtarı ister. Bu sayfa anahtarı nasıl göndereceğinizi, hangi kapsamları seçeceğinizi ve anahtarı nasıl koruyacağınızı anlatır.

#Anahtarı gönderin

Anahtarı Authorization başlığında Bearer şemasıyla gönderin:

BASH

curl https://api.verimerkezi.app/wa/me \
  -H "Authorization: Bearer vmk_live_..."

API yalnız https://api.verimerkezi.app/wa adresinde çalışır. Başka bir adresten yapılan çağrı 404 endpoint_moved döner.
Başlık yoksa 401 unauthorized, anahtar geçersizse 401 invalid_api_key döner.

#Anahtar türleri

Önek	Mod	Davranış
`vmk_live_`	Canlı	Mesajlar Meta'ya gönderilir; her başarılı mesaj 1 kredi düşer.
`vmk_test_`	Test	Mesaj Meta'ya gönderilmez, kredi düşmez; sahte `test.` kimlikleri döner. Hangi uçların simüle edildiğini Test modu sayfasında görün.

Anahtarlar panelde API → Anahtarlar sayfasında oluşturulur ve yalnız bir kez gösterilir. Sunucuda yalnız anahtarın SHA-256 özeti saklanır; kaybederseniz yeni anahtar oluşturun.

#Kapsamlar

Her anahtar yalnız verilen kapsamlardaki işlemleri yapabilir. Kapsam dışı istek 403 insufficient_scope döner ve yanıt gereken kapsamı error.required_scope alanında belirtir. Birden çok kapsamdan birini kabul eden uçlarda (GET /messages, GET /media, POST /webhooks/redeliver, POST /templates/sync) kabul edilen kapsamlar ayrıca error.required_scopes dizisinde gelir.

Kapsam	İzin verdiği işlemler
`*`	Tüm kapsamlar (tam yetki).
`messages:send`	Mesaj gönderme, okundu/yazıyor göstergesi, medya yükleme.
`messages:read`	Mesaj kayıtları, gelen medyayı listeleme ve indirme, ölü teslimleri yeniden kuyruğa alma.
`inbox:read`	`messages:read` ile aynı uçlar.
`templates:read`	Şablon listeleme, ayrıntı, doğrulama, senkron.
`templates:write`	Şablon oluşturma, düzenleme, silme, senkron.
`contacts:read`	Kişi listesi ve abonelikten çıkanlar.
`contacts:write`	Kişi ekleme (tekil ve toplu).
`profile:read`	Numaralar, işletme profili, geçmiş aktarımı durumu.
`profile:write`	Profil, numara ve hesap ayarları, saklama süreleri, KVKK silme, numara ayırma.
`reports:read`	Rapor özeti, kredi kullanımı ve kredi hareketleri.
`webhooks:read`	Webhook aboneliklerini listeleme.
`webhooks:write`	Abonelik oluşturma, güncelleme, silme, test, anahtar döndürme, yeniden teslim.
`calls:read`	Arama ayarları, izin durumu ve arama geçmişi.
`calls:write`	Arama başlatma, kabul, ret, sonlandırma, izin isteme, arama ayarları.
`flows:read`	Form listesi, ayrıntı, önizleme, metrikler.
`flows:write`	Form oluşturma, güncelleme, yayınlama, kaldırma, silme.

GET /me, GET /health, GET /credit/balance ve GET /credit/packages için ek kapsam gerekmez.

İpucu En az yetki ilkesini uygulayın. Yalnız mesaj gönderen bir bot için messages:send ve templates:read yeterlidir. Kapsam seçmeden oluşturulan anahtar * (tam yetki) alır; geçersiz kapsam adlarıyla yapılan oluşturma isteği reddedilir.

#IP kısıtı ve son kullanma

Panelde anahtara isteğe bağlı olarak şunları tanımlayabilirsiniz:

IP izin listesi: tek IP ya da CIDR aralığı. Liste dışından gelen istek 401 invalid_api_key döner.
Son kullanma tarihi: varsayılan olarak anahtar süresizdir. Süresi dolan anahtar 401 invalid_api_key döner.

#Kaba kuvvet koruması

Geçersiz ya da eksik anahtarla gelen istekler IP başına dakikada 60 ile sınırlıdır. Sınır aşılınca 429 ve Retry-After döner. Geçerli anahtarla yapılan istekler bu sınırdan etkilenmez; kalıcı yasak yoktur.

#Anahtar güvenliği

Anahtarı ortam değişkeninde ya da gizli anahtar yöneticisinde saklayın; kaynak koduna ve sürüm kontrolüne eklemeyin.
Anahtarı tarayıcı ya da mobil uygulama koduna gömmeyin. İstekleri kendi sunucunuz üzerinden yapın.
Her uygulama ve ortam için ayrı anahtar kullanın.
Anahtarları düzenli aralıklarla yenileyin: yeni anahtar oluşturun, sisteminize ekleyin, test edin, eskisini iptal edin.

#Anahtar sızarsa

Panelden anahtarı hemen iptal edin. İptal geri alınamaz; anahtar 401 dönmeye başlar.
Yeni anahtar oluşturup sisteminize ekleyin.
Panelde API → Kullanım kayıtlarından şüpheli çağrıları inceleyin.
Destek için [email protected] adresine yazın.

#İstek kimliği

Her yanıt X-Request-Id başlığı taşır. İsterseniz kendi kimliğinizi aynı başlıkla gönderebilirsiniz. Destek talebinde bu kimliği paylaşın.

#Tarayıcıdan çağrı (CORS)

API, CORS için her kaynağa izin verir (Access-Control-Allow-Origin: *). İzin verilen istek başlıkları Authorization, Content-Type, Accept, Idempotency-Key ve X-Request-Id; okunabilen yanıt başlıkları X-Request-Id, X-RateLimit-* ve Idempotent-Replay'dir.

Uyarı CORS açık olsa da API anahtarını tarayıcıda çalışan koda koymayın. Sayfayı açan herkes anahtarı görebilir. Tarayıcıdan gelen istekleri kendi sunucunuz üzerinden API'ye iletin.

Not (2.28.0): Doğrulanmış anahtar bilgisi sunucuda en fazla 15 saniye önbellekte tutulur. Panelden iptal ya da IP listesi değişikliği önbelleği hemen temizler; yönetim tarafındaki diğer değişiklikler en geç 15 saniyede etkili olur.