API Kimlik Doğrulama

AnchorSpot API'si, JWT (JSON Web Token) ve API anahtarı olmak üzere iki kimlik doğrulama yöntemini destekler. Otomasyon ve entegrasyon senaryolarında API anahtarı, kullanıcı etkileşimi gerektiren senaryolarda JWT tercih edilir.

Kimlik Doğrulama Yöntemleri

Yöntem	Kullanım Senaryosu	Sona Erme
JWT Token	İnteraktif uygulamalar, SSO entegrasyonu	1 saat (access token)
API Anahtarı	Sunucu-sunucu entegrasyonu, CI/CD, otomasyon	Yönetici iptal edene kadar

JWT Token Akışı

Token Alma

curl -X POST https://api.siperone.com/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{
    "email": "admin@otelimiz.com",
    "password": "••••••••"
  }'

Başarılı yanıt (HTTP 200):

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "rt_01HXQ2K9M7N3P4R5S6T7U8V9W0",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "read write"
}

Token Kullanımı

curl https://api.siperone.com/v1/sessions \
  -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."

Token Yenileme

Access token süresi dolmadan önce refresh token ile yenileyin:

curl -X POST https://api.siperone.com/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{
    "refresh_token": "rt_01HXQ2K9M7N3P4R5S6T7U8V9W0"
  }'

Yanıt:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "rt_02IYR3L0N8O4Q5S6T7U8V9W0X1",
  "expires_in": 3600
}

bilgi

Refresh token 30 gün boyunca geçerlidir ve yalnızca bir kez kullanılabilir. Kullanıldığında yeni bir refresh token da döndürülür (token rotation). Refresh token'ı güvenli biçimde saklayın.

API Anahtarı

Anahtar Oluşturma

Konsolda Ayarlar → API Anahtarları → Yeni Anahtar Oluştur:

1. Anahtar adını girin (örn. production-crm-integration)
2. Kapsamları seçin (read, write, admin, compliance)
3. Opsiyonel IP kısıtlaması belirtin (CIDR formatı)
4. Oluştur butonuna tıklayın

tehlike

API anahtarı yalnızca bir kez görüntülenir. Güvenli bir yere kaydedin; kaybolursa yeni anahtar üretmeniz gerekir. Eski anahtar iptal edilir.

Anahtar Kullanımı

curl https://api.siperone.com/v1/sessions \
  -H "X-API-Key: sk_live_01HXQ2K9M7N3P4R5S6T7U8V9W0"

API anahtarları sk_live_ (üretim) veya sk_test_ (test ortamı) önekiyle ayrılır. Test ortamı anahtarları gerçek veriye erişemez; yalnızca kurgusal test verisiyle çalışır.

Kapsam (Scope) Sistemi

Kapsam	İzin Verilen İşlemler
read	GET istekleri; oturumlar, misafirler, raporlar okuma
write	POST/PUT; voucher oluşturma, hotspot güncelleme
admin	DELETE; oturum sonlandırma, kullanıcı yönetimi, yapılandırma
compliance	Kanıt paketi ve audit chain dışa aktarma

Kapsam kontrolü her istek için uygulanır. Yetersiz kapsamlı token/anahtar ile istek yapılırsa:

{
  "error": "insufficient_scope",
  "message": "Bu işlem için 'write' kapsamı gereklidir",
  "required_scope": "write",
  "provided_scope": "read",
  "request_id": "req_01HXQ2K9M7N3P4R5S6T7U8V9"
}

Hız Sınırlama (Rate Limiting)

Plan	İstek / Dakika	İstek / Gün
Lite	30	5.000
Standard	100	50.000
Pro	300	500.000
Enterprise	Özel	Özel

Hız sınırı aşıldığında HTTP 429 döner:

{
  "error": "rate_limit_exceeded",
  "message": "Dakikada 100 istek sınırına ulaşıldı",
  "retry_after": 23
}

Yanıt başlıkları:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1710512400
Retry-After: 23

Hata Kodları

HTTP Kodu	Hata	Açıklama
400	bad_request	Geçersiz istek gövdesi veya parametre
401	unauthorized	Token/anahtar eksik, geçersiz veya süresi dolmuş
403	forbidden	Yetersiz kapsam veya IP kısıtlaması ihlali
404	not_found	Kaynak bulunamadı
409	conflict	Kaynak zaten mevcut
422	unprocessable	Geçerli format, iş kuralı ihlali
429	rate_limited	Hız sınırı aşıldı
500	server_error	Sunucu hatası

Tüm hata yanıtları aynı yapıyı takip eder:

{
  "error": "error_code",
  "message": "İnsan okunabilir hata açıklaması",
  "request_id": "req_01HXQ2K9M7N3P4R5S6T7U8V9",
  "timestamp": "2024-03-15T14:32:07.000Z"
}

ipucu

request_id değerini SiperOne destek ekibine bildirirseniz sorunun izlenmesi kolaylaşır. Her API isteği için benzersiz bir request_id üretilir ve yanıt başlığında da X-Request-ID olarak döner.

Güvenlik En İyi Uygulamaları

1. API anahtarlarını kaynak koduna gömmeyin — Ortam değişkenleri (ENV) veya secrets manager kullanın
2. Minimum kapsam — Entegrasyon için yalnızca gerekli kapsamı verin
3. IP kısıtlaması — Mümkünse anahtarı belirli IP adreslerine/bloklarına kısıtlayın
4. Anahtarları döndürün — Her 90 günde bir yeni anahtar üretin, eskiyi iptal edin
5. HTTPS zorunlu — HTTP üzerinden yapılan tüm istekler 301 ile HTTPS'e yönlendirilir

# Örnek: Ortam değişkeni ile güvenli kullanım
export ANCHORSPOT_API_KEY="sk_live_01HXQ2K9M7N3P4R5S6T7U8V9W0"

curl https://api.siperone.com/v1/sessions \
  -H "X-API-Key: ${ANCHORSPOT_API_KEY}"