Skip to main content
OTPless issues ID tokens as JWTs signed with the RS256 algorithm.
Your backend must verify the signature and claims before trusting the token.

JWKS (Public Keys)

To verify signatures, fetch OTPless public keys from:
  • Recommended (secure): https://otpless.com/.well-known/jwks
These contain the RSA public keys used for verifying RS256 signatures.
You must select the key where kid matches the JWT header.

Example JWT ID Token

Payload


Claim Reference


Verification Checklist

  1. Signature
    • Verify using RS256 with OTPless JWKS (https://otpless.com/.well-known/jwks).
  2. Issuer (iss)
    • Must equal https://otpless.com.
  3. Audience (aud)
    • Must equal PXXXXG1XXXX1NXXYAO.
  4. Time claims
    • exp > current time (allow ±60s skew).
    • iat and auth_time optional checks.
  5. App-specific checks
    • Ensure phone_number_verified: true before granting sensitive access.
    • Use sub as the stable user identifier.
  6. Algorithm hardening
    • Accept only RS256.
    • Reject tokens with alg: none or unexpected algorithms.

Code Examples

Node.js (Express) — jose


Java (Spring Boot) — Nimbus JOSE + JWT


Python (Flask/FastAPI) — authlib

Go (net/http + jwx + golang-jwt)

Best Practices

  • Cache JWKS (5–15 minutes). Refresh when a kid is not found.
  • Always use HTTPS JWKS endpoint in production for security.
  • Strictly check iss and aud.
  • Allow a small clock skew (30–60s).
  • Reject unexpected algorithms (only RS256).
  • Use phone_number_verified before sensitive operations.
  • Never trust a JWT by simply decoding — always verify signature.