tokens in identity management
quick notes to self, before I forget it again
Kept mixing these up in standup so writing it down properly this time. A token here just means some piece of data that proves “this request is allowed to do X” without the system having to check a username and password every single time. Different jobs need different tokens, and that’s basically the whole confusion. Below is every type I actually run into day to day, with real looking examples so it sticks.
contents
Access Token
used in → OAuth 2.0, most REST APIs
This is the actual “key” a client app uses to call an API on behalf of a user. Once someone logs in, the app gets handed an access token, and from then on it just shows this token with every request instead of asking for the password again. It is meant to be short lived, usually somewhere between 5 minutes and an hour, so if it leaks the damage window is small.
- Proves the request is authorized, not who the user is (that’s the ID token’s job)
- Usually a JWT, but can also be a random opaque string the server looks up
- Has “scopes” baked in, like read:emails or write:files, so it can’t do more than it’s meant to
example, calling an API with it
GET /api/user/profile HTTP/1.1 Host: api.example.com Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
← that long string after “Bearer” is the access token. Server checks it, sees scope=read:profile, and returns the data.
Refresh Token
used in → OAuth 2.0, mobile apps that stay logged in
The quiet backup that gets a new access token once the old one expires, without making the user log in again. Lives much longer than an access token, sometimes days or months, and is stored more carefully because if this one leaks, someone can keep minting fresh access tokens forever.
- Never sent with every API call, only sent to the auth server’s “token” endpoint
- Can be revoked server side, which instantly kills the whole session chain
- This is why “remember me” works, it’s a refresh token sitting quietly in storage
example, exchanging it for a new access token
POST /oauth/token grant_type=refresh_token refresh_token=8xLOxBtZp8... client_id=myapp123
server replies with a brand new access_token, app never had to bug the user for a password.
ID Token
used in → OpenID Connect (OIDC), “Sign in with Google” style logins
Easy to confuse with the access token but this one answers a totally different question, “who is this person” rather than “what can this request do”. It’s always a JWT, and the app reads it once at login to show the person’s name, email, profile picture etc. It’s not meant to be sent to APIs at all.
example, decoded payload
{
"iss": "https://accounts.google.com",
"sub": "10769150350006150715113082367",
"email": "rahul.dev@gmail.com",
"name": "Rahul Sharma",
"exp": 1723650000
}
app reads this, shows “Welcome Rahul” on screen, done. Not used for calling APIs.
Session Token (session cookie)
used in → classic websites, server rendered apps
The older, simpler approach, mostly for traditional websites rather than mobile apps or microservices. After login, the server creates a session record in its own database and hands the browser a small random ID in a cookie. The browser sends that cookie back automatically on every request, and the server looks up the session in its own memory or DB to know who’s asking.
- Server has to keep session state, unlike JWT based tokens which are self contained
- Easy to invalidate, just delete the session row and the user is logged out everywhere
- Usually marked HttpOnly and Secure so JavaScript can’t touch it, helps against theft
example, what the server sends back after login
Set-Cookie: sessionid=a8f5f167f44f4964e6c998dee827110c; HttpOnly; Secure; SameSite=Strict; Max-Age=3600
browser stores this automatically, resends it on every future request to that site.
JWT, the format itself
JSON Web Token, not really a “type” of token, more like a container
Worth its own note because access tokens, ID tokens, and plenty of custom tokens are all just JWTs underneath. A JWT is three base64 chunks separated by dots, header.payload.signature. Anyone can read the contents (it is not encrypted, just encoded), but only the server holding the secret key can produce a valid signature, so it can’t be tampered with without getting caught.
example, the three parts
header: { "alg": "HS256", "typ": "JWT" }
payload: { "sub": "user_492", "role": "editor", "exp": 1723650000 }
signature: HMACSHA256(base64(header)+"."+base64(payload), secretKey)
full token:
eyJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ1c2VyXzQ5MiJ9.4f9c1e8b3a...
server verifies the signature on every request, if payload was edited, signature check fails and request gets rejected.
Bearer Token
a way of using a token, not really a separate kind
This one confused me the most at first. “Bearer” just means whoever holds it, gets the access, no extra proof needed. Most access tokens are used as bearer tokens, sent in the Authorization header like Authorization: Bearer <token>. The catch is exactly what the name says, if it gets stolen, the thief can use it just as well as the real owner, there’s no extra signature needed from the client side. That’s the whole reason they’re kept short lived and always sent over HTTPS.
SAML Assertion
used in → enterprise SSO, old school corporate logins
The XML flavored older cousin of the OIDC ID token, common in big companies where one login (say, Okta or ADFS) gets you into a dozen internal tools. Instead of JSON, it’s an XML document signed by the identity provider, saying “yes, I checked, this really is rahul@company.com, and here’s what department they’re in”.
example, trimmed down assertion
<saml:Assertion>
<saml:Subject>
<saml:NameID>rahul.sharma@company.com</saml:NameID>
</saml:Subject>
<saml:AttributeStatement>
<saml:Attribute Name="Department">
<saml:AttributeValue>Engineering</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
</saml:Assertion>
browser posts this to the app after login, app trusts it because it’s digitally signed by the company’s identity provider.
API Key
used in → server to server calls, third party integrations
The simplest one on this list. Just a long static string tied to a developer account or project, not tied to a specific logged in person. No expiry by default, no “who is this user” info inside it, it just says “this call is coming from a known app”. Weaker than OAuth tokens for user level security, which is why it’s mostly used for backend to backend traffic, not for logging in actual people.
example, typical usage
GET /v1/weather?city=Jabalpur X-API-Key: sk_live_51JXk29fRhTz8...
note there’s no “user” here at all, just proof that this is a paying, registered app calling the weather service.
OTP / One Time Token
used in → 2FA, password reset links, email verification
Made to be used exactly once and then thrown away. The classic 6 digit code texted during two factor login is one form of this, but “reset your password” email links carry a one time token too, usually a long random string tied to that specific request, expiring in maybe 15 minutes.
- Once it’s used, or it expires, it’s dead, using it again does nothing
- Kept short (numeric OTPs) or hard to guess (link tokens), never reused across sessions
example, password reset link
https://app.example.com/reset-password?token=9f8b7c6a5d4e3f2g1h0i
clicking this once resets the password, clicking it again later gives “link expired or already used”.
CSRF Token
used in → web forms, protecting against cross site request forgery
Not really about who the user is, it’s about proving the request actually came from the app’s own page and not some sketchy third party site tricking the browser into submitting a form. The server drops a random token into the page’s form, and checks that the same token comes back on submit. A forged request from another site won’t have it.
example, hidden form field
<form method="POST" action="/transfer-funds"> <input type="hidden" name="csrf_token" value="d41d8cd98f00b204e98"> ... </form>
if this field is missing or wrong on submit, server rejects the request even if the session cookie was valid.
| token | answers | typical lifespan |
|---|---|---|
| Access Token | what can this request do | minutes |
| Refresh Token | can we skip login again | days to months |
| ID Token | who is this person | single login event |
| Session Cookie | which session is this | minutes to weeks |
| API Key | which app is calling | usually forever, until revoked |
| OTP | is this really you, right now | a few minutes, once |
| CSRF Token | did this form really come from us | one page load / session |
Rough way I remember it now: access token = the pass you flash at the door every time, refresh token = the membership card that gets you a new pass without re registering, ID token = your name badge, session cookie = the old school “your table number”, API key = the restaurant’s own account with the supplier, and OTP/CSRF are just extra checks so nobody can fake any of the above.
ok, that should stop me from googling this every two weeks ✎
