Kimlik doğrulama

Public API için Bearer API anahtarı, kapsam ve app/org bağlamı; istemci SDK uçlarında sahiplik kanıtı (token_hash) ve identity verification (identity_hash HMAC ya da ES256 JWT); hata yanıtları.

Public API (`/v1`)

GET /v1/apps/app_01J…/users?limit=50 HTTP/1.1
Host: api.pushizo.com
Authorization: Bearer hs_live_…

Anahtar Organizasyon → API anahtarları ekranından ya da POST /v1/apps/{app_id}/api-keys ile oluşturulur; ham değer yalnızca oluşturma ve rotasyon yanıtında görünür (API anahtarları).
Kapsam: her işlemin gerektirdiği kapsam referansta işlem başlığının altında yazar; admin tüm kapsamları içerir. Yetersiz kapsam 403 HS_FORBIDDEN.
App bağlamı: yolda {app_id} olan işlemler (/v1/apps/{app_id}/…) o app'e, /v1/notifications gibi düz işlemler app_id sorgu/gövde alanına göre çalışır. App'e bağlı anahtarda app_id verilmese de bağlı app kullanılır; org geneli anahtarda app_id zorunludur. Başka app'in kimliği 404 HS_NOT_FOUND.
Org geneli işlemler (GET /v1/apps, POST /v1/apps, GET /v1/organization*) org geneli admin anahtarı ister.
API anahtarı yalnızca /v1 rotalarında geçerlidir; /internal ve /admin oturum çerezi ister (dashboard).
IP izin listesi tanımlıysa dışındaki istekler 403 (details.reason: ip_not_allowed); süresi dolmuş/iptal edilmiş anahtar 401 HS_UNAUTHENTICATED.

Sunucu SDK'larında anahtar yapılandırmada verilir (new Pushizo({ apiKey }), Pushizo(api_key=…), pushizo.NewClient(key)…).

İstemci SDK uçları (`/sdk/v1`)

İstemci SDK'ları (tarayıcı, mobil) API anahtarı taşımaz; yalnızca App ID ile çalışır. Güvenlik iki mekanizmayla sağlanır:

Sahiplik kanıtı (`token_hash`)

Abonelik oluşturulurken cihaz token'ı (APNs/FCM/HMS token'ı, Web Push endpoint, e-posta, telefon) kaydedilir. Sonraki istekler (PATCH /sdk/v1/apps/{app_id}/subscriptions/{id}, login, logout, olaylar, teslimat geri bildirimi, in-app/inbox, tercihler) token_hash = SHA-256(token) ile aboneliğe sahip olduğunu kanıtlar; eşleşmeyen istek 403. Böylece bir abonelik kimliğini bilen üçüncü taraf onu değiştiremez.

Identity verification

App ayarında Identity verification açıksa login(external_id) ve kullanıcı güncellemeleri yalnızca sunucunuzun imzaladığı bir kanıtla kabul edilir:

Mod (`identity_verification_mode`)	Kanıt	Üretim
`hmac`	`identity_hash = HMAC-SHA256(sdk_secret, external_id)` (hex)	Sunucu SDK'ları: `Pushizo.identityHash(sdkSecret, externalId)` (Node), `Client::identityHash` (PHP) vb. `sdk_secret` App ayarları → SDK ekranından
`jwt`	ES256 JWT: `sub = external_id`, `aud = app_id`, `exp`; app'e kayıtlı genel anahtar (`kid`) ile doğrulanır	`POST /v1/apps/{app_id}/identity-keys` ile genel anahtar; sunucu SDK'larında `identityToken(...)` yardımcısı (JWT rehberi)
`both`	İkisinden biri	Geçiş dönemi için

SDK'lar kanıtı login(externalId, identityHash) ya da login(externalId, { jwt }) ile alır ve kullanıcıya ait sonraki isteklere ekler. Kanıt olmadan gelen login 403 HS_FORBIDDEN döner; anonim kullanım etkilenmez.

Gizlilik rızası

requiresPrivacyConsent açıkken SDK, setConsentGiven(true) çağrılana kadar hiçbir isteği göndermez; sunucu tarafında ek bir işaret yoktur.

Dashboard ve platform (`/internal`, `/admin`)

Oturum çerezi (hs_session, HttpOnly; Secure; SameSite=Lax) + x-csrf-token; mutasyonlarda Origin denetimi. Bu uçlar public sözleşmenin parçası değildir; tip güvenli istemci için ayrı openapi-internal.yaml üretilir. Platform admin uçları ayrıca MFA ister.

Hata yanıtları

Durum	Kod	Anlam
401	`HS_UNAUTHENTICATED`	Başlık yok, biçimi yanlış, anahtar iptal/süresi dolmuş
403	`HS_FORBIDDEN`	Kapsam yetersiz, IP izin listesi, sahiplik kanıtı/identity verification başarısız, org geneli işlem app anahtarıyla
403	`HS_ORG_SUSPENDED`	Organizasyon askıda
403	`HS_SSO_REQUIRED`	(Dashboard) yalnızca SSO org'u
404	`HS_NOT_FOUND`	Kaynak yok ya da başka kiracıya ait
421	`HS_WRONG_CELL`	İstek başka veri bölgesindeki org'a ait; `details.api_url` ile doğru kök

Kimlik doğrulama

Public API (/v1)Bağlantıyı kopyala

İstemci SDK uçları (/sdk/v1)Bağlantıyı kopyala

Sahiplik kanıtı (token_hash)Bağlantıyı kopyala

Identity verificationBağlantıyı kopyala

Gizlilik rızasıBağlantıyı kopyala

Dashboard ve platform (/internal, /admin)Bağlantıyı kopyala

Hata yanıtlarıBağlantıyı kopyala

Bu sayfada