DOCS

OAuth 2.0-authenticatie

StartpaginaVoor logistieke dienstverleners 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). Your service signs a short-lived JWT with your RSA private key; Zonos verifies it using your registered public key and returns a Bearer token scoped to your organization.

Flow-samenvatting:

  1. Genereer een RSA-keypair en registreer uw public key bij Zonos.
  2. Teken tijdens runtime een JWT-assertie met uw private key en POST deze naar het token-eindpunt.
  3. Zonos retourneert een kortlevende access token.
  4. Neem de access token op als Authorization: Bearer <token> bij elk API-verzoek.

Genereer een 4096-bits RSA-keypair en deel de public key met Zonos. Dit gebeurt eenmalig tijdens onboarding.

Genereer het keypair 

1# Generate private key
2openssl genrsa -out private_key.pem 4096
3 
4# Extract public key
5openssl rsa -in private_key.pem -pubout -out public_key.pem

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.

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).

Vereiste claims 

Claim↕Waarde↕
issUw Zonos Organization ID (bijv. "org_abc123")
subIdentificeert de aanroepende service (bijv. "checkout-service")
audMoet exact "zonos-auth" zijn
expUnix-timestamp; 60–300 seconden na iat
iatUnix-timestamp van uitgifte
jtiUnieke UUID per assertie (maakt replay-detectie mogelijk)

De JWT-header moet "alg": "RS256" en "typ": "JWT" specificeren.

Codevoorbeelden 

1import jwt, uuid, time
2 
3with open("private_key.pem") as f:
4 private_key = f.read()
5 
6now = int(time.time())
7assertion = jwt.encode(
8 {
9 "iss": "org_abc123",
10 "sub": "checkout-service",
11 "aud": "zonos-auth",
12 "iat": now,
13 "exp": now + 300,
14 "jti": str(uuid.uuid4()),
15 },
16 private_key,
17 algorithm="RS256",
18)

Stuur de getekende JWT naar het Zonos token-eindpunt om een kortlevende Bearer token te ontvangen.

Eindpunt 

POST https://auth.zonos.com/oauth/token
Content-Type: application/json

application/x-www-form-urlencoded wordt ook geaccepteerd.

Requestvelden 

Veld↕Vereist↕Waarde↕
grant_typeYes"urn:ietf:params:oauth:grant-type:jwt-bearer"
assertionYesUw getekende JWT (compact serialization)

Request en response 

1{
2 "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
3 "assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
4}
Responseveld↕Beschrijving↕
access_tokenBearer token voor alle volgende API-verzoeken
token_typeAltijd "Bearer"
expires_inSeconden tot expiry (standaard: 300)
scopeSpatie-gescheiden permissies voor deze token

Volledige codevoorbeelden 

1import requests
2 
3response = requests.post(
4 "https://auth.zonos.com/oauth/token",
5 json={
6 "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
7 "assertion": assertion,
8 },
9)
10data = response.json()
11access_token = data["access_token"]
12expires_in = data["expires_in"]

Neem de access token op als Bearer token in de Authorization-header bij elk Zonos API-verzoek.

Voorbeeldrequest 

1curl -X POST https://api.zonos.com/graphql \
2 -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \
3 -H "Content-Type: application/json" \
4 -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.

1import time, requests
2 
3_cache = {"access_token": None, "expires_at": 0}
4 
5def get_access_token():
6 if time.time() < _cache["expires_at"] - 30:
7 return _cache["access_token"]
8 
9 assertion = build_jwt_assertion()
10 data = requests.post(
11 "https://auth.zonos.com/oauth/token",
12 json={
13 "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
14 "assertion": assertion,
15 },
16 ).json()
17 
18 _cache["access_token"] = data["access_token"]
19 _cache["expires_at"] = time.time() + data["expires_in"]
20 return _cache["access_token"]

Foutreferentie 

Alle fouten volgen het OAuth 2.0 error response-formaat (RFC 6749 §5.2):

1{
2 "error": "invalid_grant",
3 "error_description": "JWT assertion has expired"
4}
HTTP-status↕error↕Oorzaak↕
400unsupported_grant_typegrant_type was not urn:ietf:params:oauth:grant-type:jwt-bearer
400invalid_requestOntbrekend of ongeldig veld
401invalid_grantOngeldige handtekening, verlopen assertie, onbekende org of niet-geregistreerde key
500server_errorInterne fout — neem contact op met Zonos support als het aanhoudt

Veelvoorkomende invalid_grant-oorzaken:

  • exp ligt in het verleden — zorg dat uw systeemklok NTP-gesynchroniseerd is
  • aud is niet exact "zonos-auth"
  • iss komt niet overeen met uw geregistreerde Organization ID
  • Public key is geroteerd maar nog niet bijgewerkt bij Zonos

Security best practices 

  • Bescherm uw private key. Bewaar deze in een dedicated secrets manager — nooit in source control, environment variables of logs.
  • Houd asserties kortlevend. 60–300 seconden is standaard; er is geen reden om langere uit te geven.
  • Neem jti op. Een unieke waarde per assertie maakt server-side replay-detectie mogelijk.
  • Roteer keypairs periodiek. Registreer een nieuwe public key bij Zonos voordat u de oude intrekt om downtime te voorkomen.
  • Log nooit access_token- of assertion-waarden. Behandel beide als credentials.
Boek een demo

Was deze pagina nuttig?

Krijg ondersteuning·Juridische documenten·© 2026 Zonos
Op deze pagina:
  • OAuth 2.0-authenticatie
  • Generate private key
  • Extract public key
  • Tokenlevenscyclus en caching
  • Foutreferentie
  • Security best practices