Autentiser dine bakendtjenester med Zonos ved hjelp av asymmetrisk nøkkelkryptografi — ingen delte hemmeligheter.
Zonos støtter maskin-til-maskin-autentisering via OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Tjenesten din signerer en kortvarig JWT med din private RSA-nøkkel; Zonos bekrefter den ved hjelp av din registrerte offentlige nøkkel og returnerer en Bearer-token som er begrenset til organisasjonen din.
Flytsammendrag:
Generer et RSA-nøkkelpar og registrer din offentlige nøkkel med Zonos.
Under kjøring signerer du en JWT-påstand med din private nøkkel og POSTER den til token-endepunktet.
Zonos returnerer en kortvarig tilgangstoken.
Inkluder tilgangstokenen som Authorization: Bearer <token> på hver API-forespørsel.
Trinn 1 — Registrer den offentlige nøkkelen din (engangsoppsett)
Generer et 4096-bits RSA-nøkkelpar og del den offentlige nøkkelen med Zonos. Dette gjøres en gang under onboarding.
Del public_key.pem med Zonos. Lagre private_key.pem i en dedikert hemmelighetsbehandler (AWS Secrets Manager, HashiCorp Vault, osv.) — aldri i versjonskontroll eller miljøvariabler.
Zonos vil registrere nøkkelen din og returnere organisasjons-ID-en din, som blir iss-kravet i alle JWT-påstander.
Trinn 2 — Bygg en JWT-påstand
Signer en JWT med RS256 ved hjelp av den private nøkkelen din. Påstanden er gyldig for en enkelt tokenbytte — hold utløpsvinduet kort (60–300 sekunder).
Tilgangstokener utløper etter 5 minutter som standard. Cache tokenen og oppfrisk proaktivt — ikke be om et nytt token på hver API-anrop. Hver oppfrisking krever en nysignert JWT-påstand.
OAuth 2.0-autentisering
OAuth 2.0-autentisering
Autentiser dine bakendtjenester med Zonos ved hjelp av asymmetrisk nøkkelkryptografi — ingen delte hemmeligheter.
Zonos støtter maskin-til-maskin-autentisering via OAuth 2.0 JWT Bearer Token Grant (RFC 7523). Tjenesten din signerer en kortvarig JWT med din private RSA-nøkkel; Zonos bekrefter den ved hjelp av din registrerte offentlige nøkkel og returnerer en Bearer-token som er begrenset til organisasjonen din.
Flytsammendrag:
Authorization: Bearer <token>på hver API-forespørsel.Trinn 1 — Registrer den offentlige nøkkelen din (engangsoppsett)
Generer et 4096-bits RSA-nøkkelpar og del den offentlige nøkkelen med Zonos. Dette gjøres en gang under onboarding.
Generer nøkkelparet
# Generate private keyopenssl genrsa -out private_key.pem 4096# Extract public keyopenssl rsa -in private_key.pem -pubout -out public_key.pemDel
public_key.pemmed Zonos. Lagreprivate_key.pemi en dedikert hemmelighetsbehandler (AWS Secrets Manager, HashiCorp Vault, osv.) — aldri i versjonskontroll eller miljøvariabler.Zonos vil registrere nøkkelen din og returnere organisasjons-ID-en din, som blir
iss-kravet i alle JWT-påstander.Trinn 2 — Bygg en JWT-påstand
Signer en JWT med
RS256ved hjelp av den private nøkkelen din. Påstanden er gyldig for en enkelt tokenbytte — hold utløpsvinduet kort (60–300 sekunder).Påkrevde krav
iss"org_abc123")sub"checkout-service")aud"zonos-auth"expiatiatjtiJWT-hodet må spesifisere
"alg": "RS256"og"typ": "JWT".Kodeeksempler
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",)Trinn 3 — Bytt påstanden mot et tilgangstoken
Send den signerte JWT-en til Zonos-tokenendepunktet for å motta en kortvarig Bearer-token.
Endepunkt
application/x-www-form-urlencodeder også godtatt.Forespørselsfelt
grant_type"urn:ietf:params:oauth:grant-type:jwt-bearer"assertionForespørsel og respons
{"grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer","assertion": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."}access_tokentoken_type"Bearer"expires_inscopeFullstendige kodeeksempler
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"]Trinn 4 — Ring Zonos API-er med tilgangstokenen
Inkluder tilgangstokenen som en
Bearer-token iAuthorization-hodet på hver Zonos API-forespørsel.Eksempelforespørsel
curl -X POST https://api.zonos.com/graphql \-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..." \-H "Content-Type: application/json" \-d '{ "query": "{ ... }" }'Tokenlevetid og caching
Tilgangstokener utløper etter 5 minutter som standard. Cache tokenen og oppfrisk proaktivt — ikke be om et nytt token på hver API-anrop. Hver oppfrisking krever en nysignert JWT-påstand.
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"]Feilreferanse
Alle feil følger OAuth 2.0-feilresponsformatet (RFC 6749 §5.2):
{"error": "invalid_grant","error_description": "JWT assertion has expired"}error↕400unsupported_grant_typegrant_typevar ikkeurn:ietf:params:oauth:grant-type:jwt-bearer400invalid_request401invalid_grant500server_errorVanlige årsaker til
invalid_grant:exper i fortiden — sørg for at systemklokken din er NTP-synkronisertauder ikke nøyaktig"zonos-auth"isssamsvarer ikke med din registrerte organisasjons-IDBeste praksis for sikkerhet
jti. En unik verdi per påstand gjør det mulig å oppdage gjentaking på serversiden.access_tokenellerassertion-verdier. Behandle begge som legitimasjon.Var denne siden nyttig?