Passaggio 1: registra la tua chiave pubblica (configurazione una tantum)
Genera una coppia di chiavi RSA a 4096 bit e condividi la chiave pubblica con Zonos. Questa operazione viene eseguita una volta durante l'onboarding.
Genera la coppia di chiavi
Condividere public_key.pem con Zonos. Negozio private_key.pem in un gestore di segreti dedicato (AWS Secrets Manager, HashiCorp Vault, ecc.) — mai nel controllo del codice sorgente o nelle variabili di ambiente.
Zonos registrerà la tua chiave e restituirà il tuo ID organizzazione, che diventa il iss rivendicazione in tutte le asserzioni del JWT.
Passaggio 2: crea un'asserzione JWT
Firma un JWT con RS256 using your private key. The assertion is valid for a single token exchange — keep the expiry window short (60–300 seconds).
Required claims
| Reclamo↕ | Valore↕ |
|---|---|
iss | Il tuo ID organizzazione Zonos (ad es. "org_abc123") |
sub | Identifica il servizio chiamante (es. "checkout-service") |
aud | Deve essere esattamente "zonos-auth" |
exp | timestamp Unix; 60–300 secondi da iat |
iat | Timestamp Unix di emissione |
jti | UUID univoco per asserzione (abilita il rilevamento della riproduzione) |
The JWT header must specify "alg": "RS256" E "typ": "JWT".
Esempi di codice
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",)Passaggio 3: scambia l'asserzione con un token di accesso
Invia il JWT firmato all'endpoint del token Zonos per ricevere un token Bearer di breve durata.
Punto finale
POST https://auth.zonos.com/oauth/token
Content-Type: application/json
application/x-www-form-urlencoded is also accepted.
Request fields
| Campo↕ | Necessario↕ | Valore↕ |
|---|---|---|
grant_type | Sì | "urn:ietf:params:oauth:grant-type:jwt-bearer" |
assertion | Sì | Il tuo JWT firmato (serializzazione compatta) |
Request and response
{ "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer", "assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}| Campo di risposta↕ | Descrizione↕ |
|---|---|
access_token | Token al portatore per tutte le successive richieste API |
token_type | Sempre "Bearer" |
expires_in | Secondi alla scadenza (default: 300) |
scope | Autorizzazioni separate da spazi concesse a questo token |
Full code examples
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"]Passaggio 4: chiama Zonos APIs con il token di accesso
Includere il token di accesso come a Bearer gettone nel Authorization intestazione su ogni richiesta Zonos API.
Richiesta di esempio
curl -X POST https://api.zonos.com/graphql \ -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \ -H "Content-Type: application/json" \ -d '{ "query": "{ ... }" }'Ciclo di vita e memorizzazione nella cache dei token
Per impostazione predefinita, i token di accesso scadono dopo 5 minuti. Memorizza il token nella cache e aggiornalo in modo proattivo: non richiedere un nuovo token a ogni chiamata API. Ogni aggiornamento richiede un'asserzione JWT appena firmata.
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"]Riferimento all'errore
Tutti gli errori seguono il formato di risposta agli errori OAuth 2.0 (RFC 6749 §5.2):
{ "error": "invalid_grant", "error_description": "JWT assertion has expired"}| Stato HTTP↕ | error↕ | Causa↕ |
|---|---|---|
400 | unsupported_grant_type | grant_type non lo era urn:ietf:params:oauth:grant-type:jwt-bearer |
400 | invalid_request | Campo mancante o non valido |
401 | invalid_grant | Firma non valida, asserzione scaduta, organizzazione sconosciuta o chiave non registrata |
500 | server_error | Errore interno: contattare l'assistenza Zonos se persistente |
Common invalid_grant cause:
expè nel passato: assicurati che l'orologio di sistema sia sincronizzato con NTPaudnon è esattamente"zonos-auth"issnon corrisponde all'ID dell'organizzazione registrata- La chiave pubblica è stata ruotata ma non ancora aggiornata con Zonos
Migliori pratiche di sicurezza
- Proteggi la tua chiave privata. Archiviala in un gestore dei segreti dedicato, mai nel controllo del codice sorgente, nelle variabili di ambiente o nei log.
- Mantieni le affermazioni di breve durata. 60–300 secondi è lo standard; non c'è motivo di emetterne di più lunghi.
- Includi
jti. Un valore univoco per asserzione consente il rilevamento della riproduzione lato server. - Ruota periodicamente le coppie di chiavi. Registra una nuova chiave pubblica con Zonos prima di revocare quella vecchia per evitare tempi di inattività.
- Non accedere mai
access_tokenOassertionvalori. Tratta entrambi come credenziali.
Autenticazione OAuth 2.0
Autentica i tuoi servizi backend con Zonos utilizzando la crittografia a chiave asimmetrica, senza segreti condivisi.
Zonos supporta l'autenticazione da macchina a macchina tramite Concessione token bearer JWT OAuth 2.0 (RFC7523). Il tuo servizio firma un JWT di breve durata con la tua chiave privata RSA; Zonos lo verifica utilizzando la chiave pubblica registrata e restituisce un token Bearer con ambito della tua organizzazione.
Riepilogo del flusso:
Authorization: Bearer <token>su ogni richiesta API.