Authorization code flow in Rest API - Deep Dive

Overview - Authorization code flow

What is it?

Authorization code flow is a way for apps to get permission to access a user's data from another service safely. It works by first getting a temporary code from the user’s login, then exchanging that code for a token that lets the app access data. This method keeps the user's password hidden from the app and adds extra security. It is commonly used in web apps to connect with services like Google or Facebook.

Why it matters

Without authorization code flow, apps would need to ask users for their passwords directly, which is risky and unsafe. This flow protects users by letting them log in through trusted services without sharing passwords. It also helps prevent hackers from stealing access tokens by using a two-step process. This makes online services safer and builds trust between users and apps.

Where it fits

Before learning this, you should understand basic web requests and what APIs are. After this, you can learn about other OAuth flows like implicit or client credentials flow, and how to use tokens to call APIs securely.

Mental Model

Core Idea

Authorization code flow is a two-step handshake where an app first gets a temporary code from the user’s login, then trades that code for a secure token to access data.

Think of it like...

It's like ordering a package at a store: first, you get a receipt (authorization code) after showing your ID, then you exchange that receipt at the counter to get your actual package (access token).

┌───────────────┐       1. User logs in and authorizes app
│   User Agent  │─────────────────────────────▶
└───────────────┘                             
         ▲                                    
         │                                    
         │ 4. Access token sent to app        
         │◀─────────────────────────────┐  
┌───────────────┐                       │  
│ Authorization │ 2. Authorization code   │  
│     Server    │◀───────────────────────┘  
└───────────────┘                       
         │                              
         │ 3. App exchanges code for token
         │─────────────────────────────▶
┌───────────────┐                      
│    Resource   │                      
│     Server    │                      
└───────────────┘                      

Build-Up - 7 Steps

1

Foundation

Understanding OAuth basics

Concept: Learn what OAuth is and why it helps apps access user data safely.

OAuth is a way for apps to get permission to use your data without asking for your password. Instead, you log in to a trusted service, and it gives the app a special key to access only what you allow.

Result

You know that OAuth separates login from data access, making apps safer.

Understanding OAuth basics is key because authorization code flow builds on this permission system to keep user data secure.

2

Foundation

Roles in authorization code flow

Concept: Identify the main players: user, app, authorization server, and resource server.

In this flow, the user is the person who owns the data. The app wants to access that data. The authorization server checks the user's identity and gives codes. The resource server holds the data and only shares it if the app has a valid token.

Result

You can name each role and understand their job in the flow.

Knowing these roles helps you follow the steps and see how security is shared among different parts.

3

Intermediate

Step 1: Getting the authorization code

🤔Before reading on: do you think the app directly gets the access token from the user login? Commit to your answer.

Concept: The app first asks the user to log in and approve access, then receives a temporary code.

The app sends the user to the authorization server’s login page with details like app ID and requested permissions. After the user logs in and agrees, the server sends back a short-lived code to the app via the user's browser.

Result

The app has a temporary code but no access token yet.

This step separates user login from token exchange, preventing the app from seeing the user's password.

4

Intermediate

Step 2: Exchanging code for access token

🤔Before reading on: do you think the authorization code can be used multiple times to get tokens? Commit to your answer.

Concept: The app sends the code securely to the authorization server to get an access token.

The app sends the code along with its secret key directly to the authorization server (not through the browser). The server verifies the code and app identity, then returns an access token and sometimes a refresh token.

Result

The app now has a token to access user data securely.

Exchanging the code server-to-server adds security by keeping tokens away from the browser and attackers.

5

Intermediate

Using the access token to call APIs

Concept: The app uses the access token to request data from the resource server.

The app includes the access token in API requests as proof of permission. The resource server checks the token and returns the requested data if valid.

Result

The app accesses user data without needing the user's password.

Tokens act like temporary keys that let apps access only what users allowed, improving security and control.

6

Advanced

Refresh tokens and long sessions

🤔Before reading on: do you think access tokens last forever? Commit to your answer.

Concept: Learn how refresh tokens let apps get new access tokens without bothering the user again.

Access tokens expire after a short time for safety. The app can use a refresh token to ask the authorization server for a new access token without user login. This keeps the session alive securely.

Result

Users stay logged in longer without re-entering credentials.

Refresh tokens balance security and user convenience by limiting token lifetime but allowing seamless renewal.

7

Expert

Security risks and mitigation in code flow

🤔Before reading on: do you think the authorization code can be intercepted and misused easily? Commit to your answer.

Concept: Understand common attacks like code interception and how PKCE protects against them.

Attackers might try to steal the authorization code during redirection. PKCE (Proof Key for Code Exchange) adds a secret generated by the app that must match during token exchange, stopping attackers from using stolen codes. This is especially important for public clients like mobile apps.

Result

Authorization code flow with PKCE is much safer against interception attacks.

Knowing these protections helps you build secure apps and avoid common vulnerabilities in OAuth implementations.

Under the Hood

Authorization code flow works by splitting user authentication and token issuance into two steps. The user authenticates directly with the authorization server, which then issues a short-lived code. The app exchanges this code for tokens via a secure back-channel, preventing exposure of tokens or credentials in the browser. The flow relies on HTTP redirects, client secrets, and optionally PKCE to ensure the code is used only by the legitimate app.

Why designed this way?

This flow was designed to improve security over earlier OAuth flows that exposed tokens in the browser, which risked interception. By using a temporary code and server-to-server exchange, it reduces token leakage. PKCE was later added to protect public clients that cannot keep secrets. The design balances user experience, security, and compatibility with web standards.

User Browser
   │
   │ 1. Request Authorization
   ▼
Authorization Server
   │
   │ 2. Redirect with Authorization Code
   ▲
User Browser
   │
   │ 3. App sends Code + Secret
   ▼
Authorization Server
   │
   │ 4. Returns Access Token
   ▲
App Server
   │
   │ 5. Uses Token to Access Resource
   ▼
Resource Server

Myth Busters - 4 Common Misconceptions

Quick: Does the app get the user's password during authorization code flow? Commit to yes or no.

Common Belief: The app must get the user's password to access their data.

Reality: The app never sees the user's password; the user logs in directly with the authorization server.

Why it matters: If developers think the app gets the password, they might build insecure login forms that risk user credentials.

Quick: Can the authorization code be reused multiple times to get tokens? Commit to yes or no.

Common Belief: The authorization code can be used repeatedly to get new tokens.

Reality: Authorization codes are single-use and expire quickly to prevent replay attacks.

Why it matters: Misusing codes can lead to security breaches where attackers reuse codes to get unauthorized access.

Quick: Is PKCE only needed for mobile apps? Commit to yes or no.

Common Belief: PKCE is only necessary for mobile or public clients without secrets.

Reality: PKCE is recommended for all clients, including web apps, to add an extra security layer.

Why it matters: Ignoring PKCE can expose apps to interception attacks, even in web environments.

Quick: Does the access token contain the user's password or sensitive info? Commit to yes or no.

Common Belief: Access tokens include the user's password or personal details.

Reality: Access tokens are opaque strings or JWTs that do not contain passwords; they only prove permission.

Why it matters: Thinking tokens hold passwords may cause developers to mishandle tokens or overexpose them.

Expert Zone

1

Authorization code flow can be combined with OpenID Connect to also get user identity information securely.

2

The timing and scope of token expiration and refresh tokens must be carefully balanced for security and user experience.

3

Implementing PKCE correctly requires synchronizing code challenge and verifier, which is often overlooked in custom clients.

When NOT to use

Authorization code flow is not ideal for machine-to-machine communication where no user is involved; client credentials flow is better there. Also, for single-page apps without a backend, implicit or authorization code with PKCE is preferred.

Production Patterns

In production, apps use HTTPS for all steps, store client secrets securely, implement PKCE for public clients, and validate tokens on resource servers. They also handle token revocation and error responses gracefully to maintain security and user trust.

Connections

Public key cryptography

Authorization code flow uses concepts similar to public key cryptography by exchanging secrets securely between parties.

Understanding secure key exchange in cryptography helps grasp why the code exchange step protects tokens from interception.

Bank ATM withdrawal process

Both involve a two-step verification: first getting a temporary authorization (card + PIN), then accessing funds.

Seeing authorization code flow like ATM steps clarifies why splitting authentication and access improves security.

Human resource onboarding

Onboarding requires approval steps before granting access to company resources, similar to user consent in authorization code flow.

Knowing how staged approvals work in HR helps understand why user consent and token exchange are separate steps.

Common Pitfalls

#1 Exposing client secret in frontend code

Wrong approach:

const clientSecret = 'mysecret'; // used in browser JavaScript

Correct approach:

Store client secret only on backend server, never in frontend code.

Root cause:

Misunderstanding that client secrets must be kept confidential and not exposed to users.

#2 Not validating redirect URI during code exchange

Wrong approach:

Accepting any redirect URI when exchanging code for token.

Correct approach:

Strictly validate redirect URI matches the one registered and used in authorization request.

Root cause:

Ignoring redirect URI validation allows attackers to intercept authorization codes.

#3 Skipping PKCE in public clients

Wrong approach:

Implementing authorization code flow without PKCE in mobile apps.

Correct approach:

Always use PKCE in public clients to prevent code interception attacks.

Root cause:

Underestimating risks of code interception in apps that cannot keep secrets.

Key Takeaways

Authorization code flow separates user login from token exchange to protect user credentials.

It uses a temporary authorization code that the app exchanges securely for access tokens.

PKCE enhances security by ensuring only the legitimate app can use the authorization code.

Access tokens let apps access user data without exposing passwords or long-term secrets.

Understanding this flow is essential for building secure apps that connect with third-party services.