REST API OAuth 2.0
Many apps ask permission to use data from another service. A photo printing site wants to read your photos, and a budgeting app wants to see your bank transactions. Handing over your password would give those apps total control. OAuth 2.0 offers a safer path. It lets you grant limited access without sharing your password.
The Valet Key Picture
Many cars ship with a valet key. The key starts the engine and opens the door, and it cannot open the trunk or the glove box. You hand it to a parking attendant without exposing your valuables. OAuth tokens work like valet keys. They give an app a narrow set of permissions for a limited time.
The Four Roles
| Role | Description | Example |
|---|---|---|
| Resource Owner | The user who owns the data | You |
| Client | The app that wants access | A photo printing site |
| Authorization Server | Issues tokens after approval | The photo service login system |
| Resource Server | The API that holds the data | The photo service API |
Scopes
A scope names one permission, such as photos.read or contacts.write. The client requests the scopes it needs, and the user sees them on the approval screen. Request the smallest set that does the job.
Authorization Code Flow with PKCE
This flow protects web apps, mobile apps, and single-page apps. PKCE adds a one-time secret that stops attackers from using a stolen code.
User ── clicks "Connect" ──→ Client App Client ── redirect + scope + code_challenge ──→ Authorization Server User ←── login and approval screen ───────────── Authorization Server User ── approves ──→ Authorization Server Client ←── redirect with one-time code ───────── Authorization Server Client ── code + code_verifier ──→ Authorization Server Client ←── access token (+ refresh token) ────── Authorization Server Client ── API call with access token ──→ Resource Server
The access token travels only between the client and the servers. The user password goes only to the authorization server, and the client app never sees it.
Client Credentials Flow
Some calls involve no user at all. A reporting service might call a payment API on its own behalf. The service sends its client id and secret to the token endpoint and receives an access token.
Backend Service ── client_id + client_secret ──→ Authorization Server Backend Service ←── access token ─────────────── Authorization Server
Use this flow only on servers that can keep secrets safe. Browser code and mobile apps cannot hide a secret.
Choosing a Flow
- Web, mobile, and single-page apps with users: authorization code with PKCE.
- Server-to-server jobs with no user: client credentials.
- Older flows such as implicit and password grant: avoid them in new projects.
OAuth and Authentication
OAuth 2.0 answers one question: what may this app do? It does not prove who the user is. OpenID Connect sits on top of OAuth 2.0 and adds an ID token that carries the identity of the user. Buttons that read "Sign in with Google" rely on OpenID Connect.
What the API Checks on Each Call
- The access token is valid and has not expired.
- The token covers the scope that the endpoint requires.
- The token belongs to the right audience.
An endpoint that needs photos.write returns 403 Forbidden when the token only carries photos.read. An expired or missing token earns a 401 Unauthorized.
Common Mistakes
Requesting Too Many Scopes
Broad requests scare users and increase damage after a leak. Ask for what the feature needs.
Open Redirect URIs
Register exact redirect URIs with the authorization server. Wildcards allow attackers to capture codes.
Storing Tokens Carelessly
Keep access tokens short-lived and store refresh tokens in secure storage only.
Skipping the State Parameter
The state value ties a response to the request that started it. It blocks cross-site request forgery during the login redirect.