Authentication and authorization

Sessions, for browsers

People in a browser don't paste API keys. Think of a coat check instead: you hand over your coat once, get a numbered ticket, and from then on the ticket is all you show.

After someone logs in, the server creates a session: a random id stored on the server, sent to the browser in a cookie. The browser attaches that cookie to every request automatically. Three cookie settings matter:

• HttpOnly: page scripts can't read it, so a script injected into the page can't steal it.
• Secure: only sent over HTTPS.
• SameSite=Lax (or Strict): not sent on most requests started by other sites. That blocks cross-site request forgery, where a hostile page makes your browser send a request with your cookie.

Signed tokens: JWT

A coat-check ticket means nothing without the rack behind it. A festival wristband is different: a guard at any gate can read it and trust it with no list to check, because it's hard to fake.

A JSON Web Token (JWT, said "jot") is that wristband. It carries claims, which are facts about the caller, signed so nobody can change them. It's three parts joined by dots, header.payload.signature, each written in base64url, a way to write any data as letters and digits that are safe in a URL. Here are the header and the payload, decoded:

{"alg": "HS256", "typ": "JWT"}
{"sub": "user_42", "scope": "campaigns:read campaigns:write", "aud": "api.shop.test", "exp": 1793000000}

• sub (subject): who the token is about. aud (audience): which API it's meant for.
• exp: when it expires, in seconds since 1970 (a Unix timestamp). iat: when it was issued.
• scope: space-separated permissions.

The signature is an HMAC of header.payload, a fingerprint that takes a secret to make. With HS256, only the server knows that secret. With RS256 or ES256 it's a public-key signature instead, which others can check without the secret.

The server can check a JWT without a database lookup. That's why JWTs are popular. It's also their weakness. A wristband keeps working until it expires, even if the person was thrown out. So keep lifetimes short, often minutes, and pair them with a refresh token: a longer-lived token that can be revoked and is used to get new short ones.

import base64, json
payload = base64.urlsafe_b64encode(json.dumps({"sub": "ada"}).encode()).decode()
print(json.loads(base64.urlsafe_b64decode(payload))["sub"])

import base64, json

token = ("eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9."
         "eyJzdWIiOiJ1c2VyXzQyIiwic2NvcGUiOiJjYW1wYWlnbnM6cmVhZCJ9."
         "x3Ns7r8OqJmXb3S7cqA2kQ6bP1eGQY0l7rZ0tqf0u9M")

def b64url_decode(part):
    return base64.urlsafe_b64decode(part + "=" * (-len(part) % 4))

header, payload, signature = token.split(".")
print(json.loads(b64url_decode(header)))
print(json.loads(b64url_decode(payload)))

The checks you must never skip

Most JWT security bugs are a skipped check. A guard who looks at a wristband's color but not its date lets in last year's crowd. Verify, in order:

1. The token has exactly three parts, and the header's alg is the one you expect. Never let the token choose. Old libraries accepted "alg": "none", meaning no signature at all.
2. The signature matches, compared with hmac.compare_digest.
3. exp is in the future.
4. aud is your API. A token issued for another service mustn't work on yours.
5. Only then, read sub and scope and authorize.

Authorization: scopes, roles and ownership

Scopes limit what a credential may do: campaigns:read but not campaigns:write. Roles group permissions for people: viewer, editor, admin.

The check that's forgotten most is object-level. Back at the hotel, your key card is real, and it opens guest rooms. It still shouldn't open room 412 when you're staying in 410. The caller may read campaigns, but is cmp_103 theirs? Without that check, changing the id in the URL shows another customer's data. This is broken object-level authorization (BOLA), first on the OWASP API Security Top 10, a widely used list of the most serious API flaws.

In plain words: being logged in isn't enough. Each time someone asks for a record, check that the record belongs to them.

Every query for a record should include the owner: WHERE id = ? AND account_id = ?.

OAuth: access on someone's behalf

"Let this app read my Google Calendar" is OAuth 2.0. Think of the valet key some cars come with. It starts the car but won't open the trunk, and you never hand over your own keys. In the same way, the app gets limited access and never sees your password. In the authorization code flow:

1. The app sends you to the provider's login page, asking for specific scopes.
2. You log in there and approve. The provider redirects back to the app with a short-lived code.
3. The app's server swaps the code for an access token (short-lived) and a refresh token.
4. The app calls the API with the access token, and uses the refresh token for new ones.

PKCE (said "pixy") protects step 2. The app makes a random secret, sends only its hash with step 1, and proves it knows the secret in step 3. It's like keeping one half of a torn ticket: a stolen code is useless without your half. Remote MCP servers use exactly this flow, which Phase 9 builds in detail.

Decoded isn't verified

Reading a letter doesn't tell you who really wrote it. Anyone can decode a JWT. Only checking the signature tells you it's genuine, so never trust the claims before that step. Set the allowed algorithm yourself, too.

Expiry

Keep tokens short-lived. A stolen wristband that expires tonight does far less harm than one that works for a year.