Autentikasi layanan backend Anda dengan Zonos menggunakan kriptografi kunci asimetris — tanpa rahasia bersama.
Zonos mendukung autentikasi mesin-ke-mesin melalui OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Layanan Anda menandatangani JWT berumur pendek dengan kunci privat RSA Anda; Zonos memverifikasinya menggunakan kunci publik terdaftar Anda dan mengembalikan token Bearer yang dibatasi ruang lingkup untuk organisasi Anda.
Ringkasan alur:
Buat pasangan kunci RSA dan daftarkan kunci publik Anda dengan Zonos.
Pada saat runtime, tandatangani asersi JWT dengan kunci privat Anda dan POSTkan ke titik akhir token.
Zonos mengembalikan token akses berumur pendek.
Sertakan token akses sebagai Authorization: Bearer <token> pada setiap permintaan API.
Langkah 1 — Daftarkan kunci publik Anda (pengaturan satu kali)
Buat pasangan kunci RSA 4096-bit dan bagikan kunci publik dengan Zonos. Ini dilakukan sekali selama onboarding.
Bagikan public_key.pem dengan Zonos. Simpan private_key.pem di pengelola rahasia khusus (AWS Secrets Manager, HashiCorp Vault, dll.) — tidak pernah di kontrol sumber atau variabel lingkungan.
Zonos akan mendaftarkan kunci Anda dan mengembalikan ID Organisasi Anda, yang menjadi klaim iss di semua asersi JWT.
Langkah 2 — Bangun asersi JWT
Tandatangani JWT dengan RS256 menggunakan kunci privat Anda. Asersi berlaku untuk pertukaran token tunggal — jaga jendela kedaluwarsa tetap pendek (60–300 detik).
Token akses berakhir dalam 5 menit secara default. Cache token dan segarkan secara proaktif — jangan minta token baru pada setiap panggilan API. Setiap penyegaran memerlukan asersi JWT yang baru ditandatangani.
Autentikasi OAuth 2.0
Autentikasi OAuth 2.0
Autentikasi layanan backend Anda dengan Zonos menggunakan kriptografi kunci asimetris — tanpa rahasia bersama.
Zonos mendukung autentikasi mesin-ke-mesin melalui OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Layanan Anda menandatangani JWT berumur pendek dengan kunci privat RSA Anda; Zonos memverifikasinya menggunakan kunci publik terdaftar Anda dan mengembalikan token Bearer yang dibatasi ruang lingkup untuk organisasi Anda.
Ringkasan alur:
Authorization: Bearer <token>pada setiap permintaan API.Langkah 1 — Daftarkan kunci publik Anda (pengaturan satu kali)
Buat pasangan kunci RSA 4096-bit dan bagikan kunci publik dengan Zonos. Ini dilakukan sekali selama onboarding.
Buat pasangan kunci
# Generate private keyopenssl genrsa -out private_key.pem 4096# Extract public keyopenssl rsa -in private_key.pem -pubout -out public_key.pemBagikan
public_key.pemdengan Zonos. Simpanprivate_key.pemdi pengelola rahasia khusus (AWS Secrets Manager, HashiCorp Vault, dll.) — tidak pernah di kontrol sumber atau variabel lingkungan.Zonos akan mendaftarkan kunci Anda dan mengembalikan ID Organisasi Anda, yang menjadi klaim
issdi semua asersi JWT.Langkah 2 — Bangun asersi JWT
Tandatangani JWT dengan
RS256menggunakan kunci privat Anda. Asersi berlaku untuk pertukaran token tunggal — jaga jendela kedaluwarsa tetap pendek (60–300 detik).Klaim yang diperlukan
iss"org_abc123")sub"checkout-service")aud"zonos-auth"expiatiatjtiTajuk JWT harus menentukan
"alg": "RS256"dan"typ": "JWT".Contoh kode
import jwt, uuid, timewith 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",)Langkah 3 — Tukar asersi untuk token akses
Kirim JWT yang ditandatangani ke titik akhir token Zonos untuk menerima token Bearer berumur pendek.
Titik akhir
application/x-www-form-urlencodedjuga diterima.Bidang permintaan
grant_type"urn:ietf:params:oauth:grant-type:jwt-bearer"assertionPermintaan dan respons
{"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer","assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}access_tokentoken_type"Bearer"expires_inscopeContoh kode lengkap
import requestsresponse = 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"]Langkah 4 — Panggil API Zonos dengan token akses
Sertakan token akses sebagai token
Bearerdi headerAuthorizationpada setiap permintaan API Zonos.Contoh permintaan
curl -X POST https://api.zonos.com/graphql \-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \-H "Content-Type: application/json" \-d '{ "query": "{ ... }" }'Siklus hidup token dan caching
Token akses berakhir dalam 5 menit secara default. Cache token dan segarkan secara proaktif — jangan minta token baru pada setiap panggilan API. Setiap penyegaran memerlukan asersi JWT yang baru ditandatangani.
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"]Referensi kesalahan
Semua kesalahan mengikuti format respons kesalahan OAuth 2.0 (RFC 6749 §5.2):
{"error": "invalid_grant","error_description": "JWT assertion has expired"}error↕400unsupported_grant_typegrant_typebukanurn:ietf:params:oauth:grant-type:jwt-bearer400invalid_request401invalid_grant500server_errorPenyebab umum
invalid_grant:expberada di masa lalu — pastikan jam sistem Anda tersinkronisasi NTPaudbukan persis"zonos-auth"isstidak cocok dengan ID Organisasi terdaftar AndaPraktik terbaik keamanan
jti. Nilai unik per asersi memungkinkan deteksi putar ulang sisi server.access_tokenatau nilaiassertion. Perlakukan keduanya sebagai kredensial.Apakah halaman ini bermanfaat?