Poyra API’sini üç farklı kimlik çağırır: Banka geri dönüş ucu (/v1/callbacks/…) ve giriş/parola uçları kimliksizdir — kimlik, uçtaki tek kullanımlık jetonun ya da üretilecek oturumun kendisidir.

​
API anahtarları

  • 256 bit rastgeleliktir; veritabanında yalnız SHA-512 özeti durur. Düz değer yalnız oluşturma yanıtında görünür — kaybederseniz geri okuyamazsınız, yenisini üretirsiniz.
  • Önek bir etikettir: sk_test_ ile sk_live_ arasında API davranış farkı yoktur. Test/canlı ayrımının gerçek yeri POS hesabının modudur — test modundaki hesap MockBank’a, canlı hesap gerçek bankaya gider.
  • En çok 10 aktif anahtar olabilir; iptal edilen anahtarın kaydı silinmez (sızıntı incelemesinin ilk sorusu “hangi anahtar ne zaman kapatıldı”dır).
Anahtar döndürme üç adımdır ve sırası tahsilatınızı korur:
  1. POST /v1/api-keys ile yenisini üretin — eskisi otomatik iptal edilmez.
  2. Yeni anahtarı sunucularınıza dağıtın, çalıştığını doğrulayın.
  3. POST /v1/api-keys/{id}/revoke ile eskisini kapatın. Bu andan itibaren eski anahtar anında 401 alır.
Son aktif anahtar iptal edilemez (409 api_key.last_active) — kendinizi kilitleyemezsiniz.
API anahtarı rol denetiminden muaftır ve tarayıcıya asla koyulmaz. Tarayıcı tarafında yapılacak tek şey, kimlik gerektirmeyen checkout sayfasına yönlendirmektir.

​
JWT ve roller

Panel kullanıcıları POST /v1/auth/login ile 10 dakikalık erişim jetonu ve 30 günlük, her kullanımda döndürülen yenileme jetonu alır. Parola sıfırlama tüm oturumları kapatır. Rol denetimi yalnız yazma isteklerinde uygulanır; okuma uçları tüm rollere açıktır. Roller yetki sırasıyla: Yetkisiz yazma isteği 403 insufficient_role döner ve denetim defterine .denied eylemi olarak düşer.

​
Platform anahtarı

Kiracı oluşturma (POST /v1/tenants), BIN kataloğu ve banka tatili yükleme gibi platform uçları yalnız X-Platform-Key kabul eder. Değer, kurulumda üretilen POYRA_PLATFORM_ADMIN_KEY sırrıdır ve sabit süreli karşılaştırmayla doğrulanır. Kiracı açılış yanıtı, kiracının ilk API anahtarını (test öneklidir) bir defalık döner.