Firma y verificación de JWT con python-jose

A JWT (JSON Web Token) is a compact, signed token that carries claims about a user. Once your FastAPI app issues a JWT at login, the client sends it back on every request, and you verify it without touching a session store.

• Stateless — the server doesn't store sessions; the signature proves authenticity.
• Tamper-evident — any change to the payload invalidates the signature.
• Portable — the same token works across services that share the secret or public key.

In this lesson we use python-jose to encode (sign) and decode (verify) tokens with claims, expiry, and audience validation.

A JWT has three Base64URL parts joined by dots: header.payload.signature.

• Header — algorithm and token type, e.g. {"alg": "HS256", "typ": "JWT"}.
• Payload — the claims (data) such as sub, exp, aud.
• Signature — keyed hash of header + payload, proving the token wasn't altered.

Standard (registered) claims you'll use most: sub (subject/user id), exp (expiry), iat (issued at), aud (audience), iss (issuer). The payload is only encoded, not encrypted, so never put secrets like passwords inside it.

Install python-jose with its cryptography backend so RSA and EC algorithms work too:

• pip install "python-jose[cryptography]"

The two functions you'll use constantly live in jose.jwt: jwt.encode(...) to sign and jwt.decode(...) to verify. Errors are raised as subclasses of JWTError, which lets you catch all token problems cleanly.

To sign a token, pass a claims dict, a secret key, and an algorithm. For symmetric signing we use HS256, where the same secret signs and verifies.

• Put the user id in sub — it must be a string.
• Keep the secret long and random; load it from an environment variable in real apps.

The result is a single URL-safe string you can hand back to the client.

jwt.decode does two things at once: it checks the signature and returns the claims. If the signature is wrong, it raises a JWTError instead of returning data.

• Pass the same algorithm(s) you signed with via algorithms=[...] — never trust the algorithm advertised in the token header alone.
• A successful decode means the token is authentic and untampered.

The example below signs a token, then verifies it and reads the claims back out.

This is the whole point of signing. If an attacker flips a single character in the payload, verification fails because the signature no longer matches.

• Catch JWTError to reject the request with 401 Unauthorized.
• Never decode with verify_signature=False in production — that skips the security check entirely.

The snippet corrupts a token and shows the verification raising an error.

Tokens should be short-lived. The exp claim is a Unix timestamp (seconds since epoch, UTC). python-jose automatically rejects expired tokens at decode time, raising ExpiredSignatureError.

• Compute expiry with timezone-aware UTC: datetime.now(timezone.utc) + timedelta(...).
• Access tokens are typically 15-30 minutes; refresh tokens last longer.

You can pass a datetime or an int for exp — jose converts datetimes to timestamps for you.

When a token's exp is in the past, jwt.decode raises ExpiredSignatureError (a subclass of JWTError). Handle it separately so you can tell the client to refresh instead of re-login.

• Catch ExpiredSignatureError first, then a generic JWTError.
• jose applies a small default leeway for clock skew; you can tune it with options.

Here we issue an already-expired token to prove the check fires.

The aud (audience) claim names who the token is for — e.g. your API. If you set it when encoding, you must pass the matching audience= when decoding, or jose raises JWTClaimsError.

• Prevents a token minted for one service from being replayed against another.
• If you omit audience= but the token has aud, validation fails — pass it explicitly.

The example signs with an audience and validates it on decode.

In a real bootcamp project you wrap signing and verifying in small helpers so routes stay clean. Bundle the standard claims — sub, exp, iat, aud, iss — in one place.

• create_access_token builds claims and signs.
• verify_token decodes with all validations and returns the payload or raises.

This pure-Python module has no FastAPI imports, so it's easy to unit-test on its own.

In FastAPI you plug verification into a dependency. OAuth2PasswordBearer pulls the token from the Authorization: Bearer ... header, then your dependency verifies it and returns the current user — or raises HTTPException(401).

• Any route that declares Depends(get_current_user) is now protected.
• Convert JWTError into a proper 401 so tampered or expired tokens are rejected with the right status.

This is framework code, so it runs inside a server, not a standalone judge.

You sign tokens with aud="fastapi-bootcamp-api". A teammate's decode call sometimes throws JWTClaimsError even for freshly issued, untampered tokens. What is the most likely cause?

You can now mint and validate JWTs with python-jose end to end:

• Encode claims with jwt.encode(claims, secret, algorithm="HS256"); keep sub a string and the secret in an env var.
• Decode with jwt.decode(token, secret, algorithms=[...]) and always pin the algorithm list.
• Tampering breaks the signature and raises JWTError — reject with 401.
• Expiry via exp auto-raises ExpiredSignatureError; handle it to trigger refresh.
• Audience via aud must be matched with audience= on decode or you get JWTClaimsError.
• In FastAPI, verify inside a Depends(get_current_user) dependency and convert errors into HTTPException(401).

Next up: refresh tokens and rotating signing keys.