OAuth 2.0 & OIDC Vocabulary: 25 Security Terms Every Developer Needs
OAuth 2.0 grant types, PKCE, OIDC tokens, scopes, claims, and identity vocabulary for backend and security engineers.
Security and identity are two of the most communication-heavy areas in software engineering. When you join a team working on authentication, API authorisation, or single sign-on, you will immediately hear terms like “auth code flow”, “PKCE”, “introspection endpoint”, and “ID token”. Getting the vocabulary wrong — or mixing up OAuth and OIDC — can lead to real misunderstandings in architecture discussions and code reviews. This guide covers the 25 terms you need to speak confidently about modern identity and authorisation.
Core OAuth 2.0 Concepts
OAuth 2.0 is an open authorisation framework that allows a third-party application to obtain limited access to a service on behalf of a user, without the user sharing their password. It defines a set of roles, token types, and flows (called grant types) for doing this securely.
“We’re using OAuth 2.0 so the mobile app can access the API without storing the user’s credentials."
"OAuth handles authorisation, not authentication — that’s an important distinction.”
Authorisation server is the component responsible for issuing tokens. It authenticates the user (or the client), validates the request, and hands out access tokens, refresh tokens, and — in OIDC flows — ID tokens.
“The authorisation server is running on port 8080 in our local stack. You’ll need to register your redirect URI there."
"We’re evaluating whether to use Keycloak or build our own authorisation server.”
Resource server is the API or service that holds the protected data. It accepts access tokens, validates them, and returns the requested resource if the token is valid and has the right permissions.
“The resource server needs to verify the token signature on every request — it shouldn’t trust tokens blindly."
"We’ve split our monolith, so now each microservice acts as its own resource server.”
Client in OAuth terminology is the application requesting access to a resource on behalf of the user. Clients come in two types:
- Public client — cannot securely store a secret (e.g. a single-page app or mobile app running on a user’s device).
- Confidential client — runs server-side and can safely store a client secret (e.g. a Node.js or Django backend).
“Because the React app is a public client, we have to use PKCE — we can’t embed a client secret in the frontend."
"Register the service as a confidential client and store the secret in Vault, not in the repo.”
Grant Types and Flows
Grant type describes the mechanism by which a client obtains an access token. OAuth 2.0 defines several grant types for different use cases.
Authorisation Code grant is the recommended flow for applications acting on behalf of a user. The user logs in at the authorisation server, which redirects back to the client with a short-lived code. The client exchanges that code for tokens at a back-channel endpoint, keeping tokens out of the browser’s URL bar.
“Use the authorisation code flow — never the implicit flow. The implicit flow is deprecated for good reason."
"The code is single-use and expires in 60 seconds, so exchange it immediately.”
Client Credentials grant is used for machine-to-machine (M2M) communication where there is no human user involved. The client authenticates with its own credentials and receives an access token representing itself, not a user.
“The batch job uses the client credentials grant to call the data pipeline API. There’s no user context here."
"Make sure the service account only has the scopes it actually needs — least privilege applies here too.”
Device Flow (also called the Device Authorisation Grant) is designed for devices with limited input capability — smart TVs, CLI tools, IoT devices. The device displays a short code, the user completes authorisation on a separate device (e.g. their phone), and the original device polls until it receives a token.
“We implemented the device flow for the CLI tool so engineers can authenticate without pasting tokens manually."
"The device polls every five seconds and the code expires after ten minutes.”
PKCE (Proof Key for Code Exchange, pronounced “pixie”) is a security extension to the authorisation code flow. The client generates a random secret called the code verifier, hashes it to produce a code challenge, and sends the challenge with the initial request. When exchanging the code for tokens, the client proves it holds the original verifier. This prevents authorisation code interception attacks — critical for public clients.
“PKCE is mandatory now for all public clients. It’s not optional."
"The code challenge method should be S256 — plain is only for legacy clients that can’t do hashing.”
Tokens and Their Structure
Access token is the credential used to call a protected resource. It is typically a short-lived string (often a JWT) that the resource server validates on every request. Its lifetime is deliberately short — commonly 5 to 60 minutes — to limit the damage if it is leaked.
“Pass the access token in the Authorization header as a Bearer token."
"The access token is expiring in 30 seconds — the client should use the refresh token to get a new one.”
Refresh token is a longer-lived credential used to obtain new access tokens without requiring the user to log in again. It is exchanged directly with the authorisation server, never sent to resource servers.
“Store refresh tokens securely — in an HTTP-only cookie or server-side session, never in localStorage."
"Refresh token rotation is enabled, so every time you use a refresh token you’ll get a new one back.”
JWT (JSON Web Token, pronounced “jot”) is a compact, URL-safe token format used widely for access tokens and ID tokens. A JWT has three base64url-encoded parts separated by dots:
- Header — metadata about the token, including the signing algorithm (e.g. RS256).
- Payload — the claims: data about the subject, issuer, expiry, scopes, and any custom fields.
- Signature — a cryptographic value that lets recipients verify the token has not been tampered with.
“Paste the token into jwt.io and check the expiry claim — it looks like it’s already expired."
"We’re using RS256 so the resource server can verify using the public key without calling the authorisation server.”
OIDC, Identity, and Claims
OIDC (OpenID Connect) is an identity layer built on top of OAuth 2.0. While OAuth 2.0 handles authorisation (what you can do), OIDC handles authentication (who you are). It adds a standardised ID token and a UserInfo endpoint to the OAuth flows.
“We need OIDC, not just OAuth — we want to know who the user is, not just that they have access."
"OIDC is OAuth 2.0 plus an identity layer. Think of OAuth as the foundation.”
ID token is a JWT issued by the OIDC provider that contains identity information about the authenticated user. It is intended for the client, not the resource server, and must not be used as an access token for calling APIs.
“The ID token contains the user’s name and email — use it to populate the profile UI."
"Don’t send the ID token to your API. That’s not what it’s for. Use the access token.”
Scope is a mechanism for requesting specific permissions. The client declares which scopes it needs in the authorisation request. Common OIDC scopes include openid (required for OIDC), profile, email, and offline_access (for refresh tokens).
“Add
offline_accessto the scope request if you want a refresh token."
"The user only consented to theread:messagesscope — this client isn’t allowed to delete anything.”
Claim is a key-value pair inside a JWT payload. Standard claims include sub (subject/user ID), iss (issuer), exp (expiry), iat (issued at), and aud (audience). Custom claims carry application-specific data like roles or tenant IDs.
“The
subclaim is the canonical user identifier — use it for linking to your own user records, not the email."
"We’re adding a customtenant_idclaim to the token so services know which organisation the user belongs to.”
Introspection is an endpoint defined in RFC 7662 that allows a resource server to query the authorisation server to check whether a token is active and retrieve its metadata. This is an alternative to local JWT validation.
“Legacy services that can’t validate JWTs locally call the introspection endpoint on every request."
"Introspection adds latency and load on the authorisation server — prefer local validation where possible.”
Token revocation is the ability to invalidate a token before it naturally expires. RFC 7009 defines a revocation endpoint. This is essential for logout flows and for responding to security incidents.
“When the user logs out, call the revocation endpoint to invalidate the refresh token immediately."
"Access tokens are hard to revoke because they’re validated locally. That’s why keeping them short-lived matters.”
How to Use These in Conversation
Understanding the terms is the first step — using them naturally in team discussions is the goal. Here are four scenarios you are likely to encounter.
In a security review: “The mobile app is a public client, so we can’t use client credentials. We need the authorisation code flow with PKCE and a short-lived access token. Refresh token rotation should be enabled, and we should revoke tokens on logout.”
In an architecture discussion: “Service A needs to call Service B. There’s no user involved, so we’ll use the client credentials grant. Service B acts as the resource server and validates the JWT locally using the authorisation server’s public key. No introspection needed.”
In a code review: “You’re storing the ID token in localStorage — don’t do that. Store the access token in memory and the refresh token in an HTTP-only cookie. Also check the aud claim on the access token to make sure it’s intended for this resource server.”
In an incident post-mortem: “A refresh token was exposed in a log file. We called the revocation endpoint immediately. Because access tokens are short-lived (15 minutes), the exposure window was limited. Going forward, we’re filtering tokens out of logs at the middleware layer.”
Quick Reference
| Term | What it is | Key point |
|---|---|---|
| OAuth 2.0 | Authorisation framework | Handles what an app can do, not who the user is |
| OIDC | Identity layer on OAuth 2.0 | Adds authentication — who the user is |
| Access token | Credential for API calls | Short-lived; sent in Authorization header |
| Refresh token | Credential for renewing access tokens | Long-lived; never sent to resource servers |
| ID token | JWT with user identity | For the client only; not for API authorisation |
| JWT | Token format (header.payload.signature) | Verified locally using signing key |
| PKCE | Code exchange security extension | Required for public clients |
| Scope | Requested permissions | Declared at authorisation request time |
| Claim | Key-value pair inside a JWT | sub, exp, aud are standard claims |
| Introspection | Server-side token validation endpoint | Use when local JWT validation is not possible |