Authenticeer uw backend-services bij Zonos met asymmetrische sleutelcryptografie — zonder gedeelde secrets.
Zonos ondersteunt machine-to-machine-authenticatie via OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Uw service tekent een kortlevende JWT met uw RSA private key; Zonos verifieert deze met uw geregistreerde public key en retourneert een Bearer token die gebonden is aan uw organisatie.
Flow-samenvatting:
Genereer een RSA-keypair en registreer uw public key bij Zonos.
Teken tijdens runtime een JWT-assertie met uw private key en POST deze naar het token-eindpunt.
Zonos retourneert een kortlevende access token.
Neem de access token op als Authorization: Bearer <token> bij elk API-verzoek.
Stap 1 — Registreer uw public key (eenmalige setup)
Genereer een 4096-bits RSA-keypair en deel de public key met Zonos. Dit gebeurt eenmalig tijdens onboarding.
Deel public_key.pem met Zonos. Bewaar private_key.pem in een dedicated secrets manager (AWS Secrets Manager, HashiCorp Vault, enz.) — nooit in source control of environment variables.
Zonos registreert uw key en retourneert uw Organization ID, die de iss-claim wordt in alle JWT-asserties.
Stap 2 — Bouw een JWT-assertie
Teken een JWT met RS256 met uw private key. De assertie is geldig voor één token-uitwisseling — houd het expiry-venster kort (60–300 seconden).
Access tokens verlopen standaard na 5 minuten. Cache de token en vernieuw proactief — vraag niet bij elke API-aanroep een nieuwe token aan. Elke vernieuwing vereist een nieuw getekende JWT-assertie.
OAuth 2.0-authenticatie
OAuth 2.0-authenticatie
Authenticeer uw backend-services bij Zonos met asymmetrische sleutelcryptografie — zonder gedeelde secrets.Zonos ondersteunt machine-to-machine-authenticatie via OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Uw service tekent een kortlevende JWT met uw RSA private key; Zonos verifieert deze met uw geregistreerde public key en retourneert een Bearer token die gebonden is aan uw organisatie.
Flow-samenvatting:
Authorization: Bearer <token>bij elk API-verzoek.Stap 1 — Registreer uw public key (eenmalige setup)
Genereer een 4096-bits RSA-keypair en deel de public key met Zonos. Dit gebeurt eenmalig tijdens onboarding.
Genereer het keypair
# Generate private keyopenssl genrsa -out private_key.pem 4096# Extract public keyopenssl rsa -in private_key.pem -pubout -out public_key.pemDeel
public_key.pemmet Zonos. Bewaarprivate_key.pemin een dedicated secrets manager (AWS Secrets Manager, HashiCorp Vault, enz.) — nooit in source control of environment variables.Zonos registreert uw key en retourneert uw Organization ID, die de
iss-claim wordt in alle JWT-asserties.Stap 2 — Bouw een JWT-assertie
Teken een JWT met
RS256met uw private key. De assertie is geldig voor één token-uitwisseling — houd het expiry-venster kort (60–300 seconden).Vereiste claims
iss"org_abc123")sub"checkout-service")aud"zonos-auth"zijnexpiatiatjtiDe JWT-header moet
"alg": "RS256"en"typ": "JWT"specificeren.Codevoorbeelden
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",)Stap 3 — Wissel de assertie in voor een access token
Stuur de getekende JWT naar het Zonos token-eindpunt om een kortlevende Bearer token te ontvangen.
Eindpunt
application/x-www-form-urlencodedwordt ook geaccepteerd.Requestvelden
grant_type"urn:ietf:params:oauth:grant-type:jwt-bearer"assertionRequest en response
{"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer","assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}access_tokentoken_type"Bearer"expires_inscopeVolledige codevoorbeelden
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"]Stap 4 — Roep Zonos API's aan met de access token
Neem de access token op als
Bearertoken in deAuthorization-header bij elk Zonos API-verzoek.Voorbeeldrequest
curl -X POST https://api.zonos.com/graphql \-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \-H "Content-Type: application/json" \-d '{ "query": "{ ... }" }'Tokenlevenscyclus en caching
Access tokens verlopen standaard na 5 minuten. Cache de token en vernieuw proactief — vraag niet bij elke API-aanroep een nieuwe token aan. Elke vernieuwing vereist een nieuw getekende JWT-assertie.
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"]Foutreferentie
Alle fouten volgen het OAuth 2.0 error response-formaat (RFC 6749 §5.2):
{"error": "invalid_grant","error_description": "JWT assertion has expired"}error↕400unsupported_grant_typegrant_typewas nieturn:ietf:params:oauth:grant-type:jwt-bearer400invalid_request401invalid_grant500server_errorVeelvoorkomende
invalid_grant-oorzaken:expligt in het verleden — zorg dat uw systeemklok NTP-gesynchroniseerd isaudis niet exact"zonos-auth"isskomt niet overeen met uw geregistreerde Organization IDBest practices voor beveiliging
jtiop. Een unieke waarde per assertie maakt server-side replay-detectie mogelijk.access_token- ofassertion-waarden. Behandel beide als credentials.Was deze pagina nuttig?