OAuth 2.0

Overview

OAuth 2.0 is an authorisation framework that lets one application access resources on another system on a user's behalf, without the user handing over their password. Instead, the user approves a request at the system that holds their account, and the application receives an access token: a credential limited in what it can do, which resource it can reach and how long it lasts. The application presents that token when calling the API.

An everyday analogy is the valet key for a car. A valet key starts the engine and opens the driver's door, but it will not open the boot or the glovebox, and you can take it back at any time. You do not give the valet your house keys. OAuth gives applications a valet key to your data: enough to do a specific job, nothing more, revocable without changing your password.

OAuth 2.0 is everywhere: "connect your calendar", "sign in with" buttons (through OpenID Connect, which builds on OAuth), and machine-to-machine API access. It matters a great deal in AI systems, where agents call tools and APIs on behalf of users. Scoped, short-lived tokens are the standard way to let an agent act with limited, auditable permissions. See OAuth for tool access and MCP for how this applies to agents.

What it is

OAuth defines four roles and a set of flows, called grant types.

Clients are either confidential, able to keep a secret (a server-side app), or public, unable to keep one (a mobile or single-page app). This distinction decides which flows and protections apply.

Where it came from

OAuth 1.0 emerged from a community effort in 2007 to replace the practice of sharing passwords with third-party sites, and was published by the IETF as RFC 5849 in 2010. It required clients to sign each request cryptographically, which was hard to implement.

OAuth 2.0 was published in October 2012 as RFC 6749, with bearer token usage in RFC 6750. It dropped request signing in favour of TLS and introduced multiple grant types. Further standards followed: PKCE (Proof Key for Code Exchange, RFC 7636, 2015), token introspection (RFC 7662), token revocation (RFC 7009), device authorisation (RFC 8628), authorisation server metadata (RFC 8414), JWT access token profile (RFC 9068), resource indicators (RFC 8707), DPoP for sender-constrained tokens (RFC 9449), and the OAuth 2.0 Security Best Current Practice, RFC 9700, in January 2025. OAuth 2.1 is being developed in the IETF as a consolidation of OAuth 2.0 and these best practices; it requires PKCE for the authorisation code flow and removes the implicit and password grants.

How it works

Authorisation code flow with PKCE

This is the recommended flow for apps acting for a user.

1. The client creates a random code_verifier and derives a code_challenge from it with SHA-256.
2. It redirects the user's browser to the authorisation server with its client ID, requested scopes, a redirect URI, a state value and the code challenge.
3. The user signs in at the authorisation server and approves the requested scopes.
4. The server redirects back to the client's registered redirect URI with a short-lived authorisation code and the state.
5. The client checks state, then sends the code and the original code_verifier to the token endpoint, over a back channel.
6. The server checks that the verifier matches the challenge and returns an access token and, optionally, a refresh token.
7. The client calls the API with Authorization: Bearer <token>.
8. The resource server validates the token, checks scope and audience, and serves the request.

PKCE ensures that someone who intercepts the code cannot exchange it, because they do not have the verifier.

Client credentials flow

For machine-to-machine access with no user, a confidential client authenticates directly to the token endpoint and receives a token for its own permissions.

Device authorisation flow

For devices without a browser or keyboard, such as a TV or a command-line tool, the device shows a code; the user approves on a phone or laptop while the device polls for the token.

Refresh

When an access token expires, the client uses a refresh token to get a new one. Refresh token rotation issues a new refresh token each time and detects reuse of old ones.

Key concepts and terms

A worked example

This scenario is illustrative. A company builds a meeting-assistant agent that reads a user's calendar and drafts agendas. The agent should read events but never delete them, and access should stop when an employee leaves.

The team registers the agent as a confidential client with the company's authorisation server. The registered redirect URI is exact, https://assistant.example.internal/callback. The agent requests two scopes: calendar.events.read and docs.create. When a user first connects, they see a consent screen listing both, and approve.

Using the authorisation code flow with PKCE, the agent receives an access token valid for 10 minutes and a refresh token valid for 30 days with rotation. The calendar API checks that the token's audience is the calendar service and that it contains calendar.events.read; a test call to delete an event returns 403. Tokens are stored encrypted in a vault, never in logs. When an employee leaves, their account is disabled at the identity provider; the next refresh fails and access ends within 10 minutes without any change to the agent. An audit log records each API call with the user and client IDs, so actions taken by the agent are traceable.

Strengths and limitations

Strengths:

• Users never share passwords with third-party applications.
• Fine-grained, revocable, time-limited access through scopes and token lifetimes.
• Flows for web, mobile, devices and services.
• A large ecosystem of standards, libraries and identity providers.
• Central control and auditing at the authorisation server.

Limitations:

• A framework, not a single protocol; many options create room for insecure choices.
• Bearer tokens can be replayed if stolen unless sender-constrained.
• Not an authentication protocol on its own; use OpenID Connect for sign-in.
• Scope design is hard, and coarse scopes undermine least privilege.
• Older flows, such as implicit and password grants, are insecure but still found in legacy systems.

How it compares with alternatives

Practical guidance and best practices

1. Use the authorisation code flow with PKCE for every client acting for a user, including confidential clients.
2. Do not use the implicit or resource owner password grants.
3. Register exact redirect URIs and match them exactly.
4. Keep access tokens short-lived and use refresh token rotation.
5. Validate audience, issuer, expiry and scope on every API request.
6. Request the smallest scopes needed and design scopes around real actions.
7. Consider sender-constrained tokens (DPoP or mTLS) for high-value APIs.
8. Store tokens securely, for example with HashiCorp Vault, and never log them.
9. Follow RFC 9700 and the OAuth 2.1 direction when designing new systems.

Common mistakes

• Using an access token as proof of who the user is, instead of an OpenID Connect ID token.
• Accepting tokens without checking that they were issued for this API.
• Allowing wildcard or loosely matched redirect URIs.
• Storing tokens in browser local storage where scripts can read them.
• Requesting broad scopes like full mailbox access when read-only would do.
• Embedding client secrets in mobile apps or front-end code.

Frequently asked questions

Is OAuth 2.0 for authentication or authorisation?

Authorisation. It grants an application access to resources. Authentication, proving who the user is to the application, is handled by OpenID Connect, which adds ID tokens on top of OAuth.

What is PKCE and do I need it?

PKCE links the code exchange to the client that started the flow, so an intercepted code is useless. Current best practice is to use it with every authorisation code flow, and OAuth 2.1 requires it.

What is OAuth 2.1?

An IETF effort to consolidate OAuth 2.0 with later security best practices into one document. It requires PKCE, removes the implicit and password grants, and requires exact redirect URI matching.

Are access tokens always JWTs?

No. They can be opaque strings that the resource server checks through introspection, or structured JWTs that it validates locally. RFC 9068 defines a standard JWT profile for access tokens.

How should AI agents use OAuth?

Agents should obtain user-delegated tokens with narrow scopes through standard flows, use short lifetimes, and never receive the user's password. Each tool call should carry a token limited to that tool's resource.

How do I revoke access?

Users or administrators revoke grants at the authorisation server. Refresh tokens stop working, and access tokens expire soon after; for immediate effect, resource servers can use introspection or short token lifetimes.

Glossary

• Client: an application requesting access.
• Authorization server: the system that issues tokens.
• Resource server: the API that accepts tokens.
• Access token: a short-lived credential for an API.
• Refresh token: a credential for obtaining new access tokens.
• Scope: a named permission.
• PKCE: Proof Key for Code Exchange.
• DPoP: Demonstrating Proof of Possession, binding tokens to a key.
• Grant type: a method for obtaining tokens.
• Consent: a user's approval of access.

Summary

OAuth 2.0, published as RFC 6749 in 2012, lets applications access APIs on a user's behalf with scoped, short-lived tokens instead of passwords. The authorisation code flow with PKCE is the recommended path for user-facing apps, client credentials serves machine-to-machine access, and the device flow covers input-limited devices. Security depends on careful choices: exact redirect URIs, audience and scope checks, short lifetimes, rotation and, for sensitive APIs, sender-constrained tokens, as consolidated in RFC 9700 and the OAuth 2.1 work. For sign-in, pair it with OpenID Connect.

Related

It belongs to Security and governance in my stack, under MLOps and AI infrastructure. Others in the same group: