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.