Adım 1 — Ortak anahtarınızı kaydedin (tek seferlik ayar)
4096 bitlik RSA anahtar çifti oluşturun ve ortak anahtarı Zonos'a gönderin. Bu, ekleme sırasında bir kez yapılır.
Anahtar çiftini oluşturun
# Özel anahtarı oluşturunopenssl genrsa -out private_key.pem 4096 openssl rsa - private_key.pem -pubout -out public_key.pempublic_key.pem dosyasını Zonos'a gönderin. private_key.pem dosyasını bir özel sırlar yöneticisinde saklayın (AWS Secrets Manager, HashiCorp Vault, vb.) — asla kaynak kontrolünde veya ortam değişkenlerinde saklamayın.
Zonos anahtarınızı kaydettiğinde Kuruluş Kimliğinizi döndürür, bu da tüm JWT onaylamalarında iss talebi olur.
Adım 2 — JWT iddiası oluşturun
RS256 kullanarak özel anahtarınızla bir JWT imzalayın. İddia tek bir belirteç değişimi için geçerlidir — son kullanma penceresini kısa tutun (60–300 saniye).
Gerekli talepler
| Talep↕ | Değer↕ |
|---|---|
iss | Zonos Kuruluş Kimliğiniz (örn. "org_abc123") |
sub | Çağıran hizmeti tanımlar (örn. "checkout-service") |
aud | Tam olarak "zonos-auth" olmalı |
exp | Unix zaman damgası; iat öğesinden 60–300 saniye |
iat | Veriliş Unix zaman damgası |
jti | İddia başına benzersiz UUID (yeniden yürütme tespitini etkinleştirir) |
JWT başlığı "alg": "RS256" ve "typ": "JWT" belirtmelidir.
Kod örnekleri
import jwt, uuid, time with open("private_key.pem") as f: private_key = f.read() now = int(time.time())assertion = jwt.encode( { "iss": "org_abc123", "sub": "checkout-service", "aud": "zonos-auth", "iat": now, "exp": now + 300, "jti": str(uuid.uuid4()), }, private_key, algorithm="RS256",)Adım 3 — İddiayı erişim belirteci için değiştirin
İmzalı JWT'yi Zonos belirteç uç noktasına göndererek kısa ömürlü bir Bearer belirteci alın.
Uç nokta
POST https://auth.zonos.com/oauth/token
Content-Type: application/json
application/x-www-form-urlencoded de kabul edilir.
İstek alanları
| Alan↕ | Gerekli↕ | Değer↕ |
|---|---|---|
grant_type | Evet | "urn:ietf:params:oauth:grant-type:jwt-bearer" |
assertion | Evet | İmzalanmış JWT'niz (kompakt seri hale getirme) |
İstek ve yanıt
{ "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer", "assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}| Yanıt alanı↕ | Açıklama↕ |
|---|---|
access_token | Sonraki tüm API istekleri için Bearer belirteci |
token_type | Her zaman "Bearer" |
expires_in | Son kullanmaya kadar geçen saniyeler (varsayılan: 300) |
scope | Bu belirtece verilen boşlukla ayrılmış izinler |
Tam kod örnekleri
import requests response = requests.post( "https://auth.zonos.com/oauth/token", json={ "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer", "assertion": assertion, },)data = response.json()access_token = data["access_token"]expires_in = data["expires_in"]Adım 4 — Erişim belirteci ile Zonos API'lerini çağırın
Erişim belirtecini Authorization başlığında Bearer belirteci olarak her Zonos API isteğine ekleyin.
Örnek istek
curl -X POST https://api.zonos.com/graphql \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json" \ -d '{ "query": "{ ... }" }'Belirteç yaşam döngüsü ve önbelleğe alma
Erişim belirtecileri varsayılan olarak 5 dakika içinde sona erer. Belirteci önbelleğe alın ve proaktif olarak yenileyin — her API çağrısında yeni bir belirteç istemeyin. Her yenileme yeni bir imzalanmış JWT iddiası gerektirir.
import time, requests _cache = {"access_token": None, "expires_at": 0} def get_access_token(): if time.time() < _cache["expires_at"] - 30: return _cache["access_token"] assertion = build_jwt_assertion() data = requests.post( "https://auth.zonos.com/oauth/token", json={ "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer", "assertion": assertion, }, ).json() _cache["access_token"] = data["access_token"] _cache["expires_at"] = time.time() + data["expires_in"] return _cache["access_token"]Hata referansı
Tüm hatalar OAuth 2.0 hata yanıtı biçimini izler (RFC 6749 §5.2):
{ "error": "invalid_grant", "error_description": "JWT assertion has expired"}| HTTP Durum↕ | error↕ | Neden↕ |
|---|---|---|
400 | unsupported_grant_type | grant_type tam olarak urn:ietf:params:oauth:grant-type:jwt-bearer değildi |
400 | invalid_request | Eksik veya hatalı biçimlendirilmiş alan |
401 | invalid_grant | Geçersiz imza, süresi dolmuş iddia, bilinmeyen kuruluş veya kayıtlı olmayan anahtar |
500 | server_error | İç hata — devam ederse Zonos desteğine başvurun |
Yaygın invalid_grant nedenleri:
expgeçmişte — sistem saatinizin NTP ile senkronize olduğundan emin olunaudtam olarak"zonos-auth"değilisskayıtlı Kuruluş Kimliğinizle eşleşmiyor- Ortak anahtar döndürüldü ancak henüz Zonos'ta güncellenmedi
Güvenlik en iyi uygulamaları
- Özel anahtarınızı koruyun. Bunu bir özel sırlar yöneticisinde saklayın — asla kaynak kontrolünde, ortam değişkenlerinde veya günlüklerde saklamayın.
- İddiaları kısa ömürlü tutun. 60–300 saniye standarttır; daha uzun olanları vermeyin.
jtiekleyin. İddia başına benzersiz bir değer sunucu tarafı yeniden yürütme tespitini etkinleştirir.- Anahtar çiftlerini düzenli olarak döndürün. Eski olanı iptal etmeden önce Zonos'a yeni bir ortak anahtar kaydedin.
- Hiçbir zaman
access_tokenveyaassertiondeğerlerini günlüğe kaydetmeyin. Her ikisini de kimlik bilgileri olarak değerlendirin.
OAuth 2.0 kimlik doğrulaması
Asimetrik anahtar şifrelemesi kullanarak Zonos ile arka uç hizmetlerinizi doğrulayın — paylaşılan sırlar yok.
Zonos, OAuth 2.0 JWT Bearer Token Grant (RFC 7523) aracılığıyla makine-makine kimlik doğrulamasını destekler. Hizmetiniz RSA özel anahtarınızla kısa ömürlü bir JWT imzalar; Zonos, kayıtlı ortak anahtarınızı kullanarak doğrular ve kuruluşunuza kapsamlı bir Bearer belirteci döndürür.
Akış özeti:
Authorization: Bearer <token>olarak ekleyin.