How to Implement OAuth in Your App: A Step-by-Step Guide

This is a practical walkthrough of adding OAuth 2.0 to a web application so users can connect a third-party account, using the Authorization Code flow with PKCE. The example is a SaaS product connecting a user's calendar, but the steps apply to most providers.

It isn't a substitute for the provider's documentation. Endpoints, scopes and requirements differ, so keep the provider's developer docs open as you go.

Before you start#

Decide three things:

1. Which provider and which API. For example, a calendar API.
2. Which scopes you need. Choose the narrowest scopes that support the feature. Read-only if you only display data.
3. Where tokens will live. In a server-side store, encrypted. Not in the browser.

Step 1: Register an OAuth application#

In the provider's developer console, create an OAuth application (sometimes called a client or app registration). You'll receive:

• A client ID, which is public.
• A client secret, which must stay on your server.

Register your redirect URI, the URL on your backend the provider will send users back to, for example https://app.example.com/oauth/callback. Most providers require an exact match, including scheme, host, path and trailing slash.

Some providers also require you to configure a consent screen, list the scopes you'll request, or submit the app for review before it can be used by the public. Check this early; review can take time.

Step 2: Build the authorization request#

When a user clicks "Connect calendar", your backend prepares the request:

1. Generate a random state value and store it in the user's session. It ties the callback to this request and protects against cross-site request forgery.
2. Generate a random code verifier (a high-entropy string) and store it in the session.
3. Compute the code challenge: the base64url-encoded SHA-256 hash of the verifier.
4. Redirect the user to the provider's authorization endpoint with these parameters:

Some providers need extra parameters to issue a refresh token, often something like requesting offline access. Check the docs.

Step 3: The user approves access#

The user signs in at the provider if necessary, reviews the requested permissions and approves or denies. Your application isn't involved in this step, and never sees the user's password.

Step 4: Handle the callback#

The provider redirects to your callback URL with either an authorization code and the state, or an error.

In your callback handler:

1. If there's an error, show a helpful message. A user cancelling is normal, not a failure.
2. Compare the returned state with the one in the session. If it doesn't match, stop.
3. Retrieve the code verifier from the session.

Step 5: Exchange the code for tokens#

From your backend, send a POST to the provider's token endpoint with:

• grant_type=authorization_code
• The code
• The redirect_uri (the same value as before)
• The code_verifier
• Your client credentials, using the authentication method the provider specifies

A successful response includes an access_token, usually an expires_in value, often a refresh_token, and the granted scope.

Authorization codes are short-lived and single-use. Exchange them immediately.

Step 6: Store the connection#

Save a connection record linked to the user and tenant, containing:

• Encrypted access and refresh tokens.
• The expiry time, calculated from expires_in.
• The scopes actually granted.
• The provider's identifier for the connected account, if available.

Then redirect the user back to the integration page showing it as connected.

Step 7: Call the API#

Send the access token in the Authorization header:

GET /calendar/v3/users/me/calendarList HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer ACCESS_TOKEN

Make these calls from your server. Handle rate limits and pagination according to the provider's API documentation.

Step 8: Refresh expired tokens#

Before calling the API, check whether the token has expired or is about to. If so, call the token endpoint with grant_type=refresh_token and the stored refresh token.

Save the new access token and expiry, and save the new refresh token if one is returned. Some providers rotate refresh tokens and invalidate the old one.

If refresh fails with invalid_grant, the user has probably revoked access or the refresh token has expired. Mark the connection as needing reauthorization and ask the user to reconnect.

Step 9: Support disconnecting#

Give users a "Disconnect" option. When used, call the provider's revocation endpoint if it has one, delete the stored tokens and stop any background work that used the connection.

Testing checklist#

• Connect successfully with a test account.
• Cancel at the consent screen.
• Tamper with the state parameter and confirm the callback rejects it.
• Connect two different users and confirm each sees only their own data.
• Revoke access from the provider's account settings and confirm your app detects it.
• Let an access token expire and confirm refresh works.
• Disconnect and confirm tokens are removed.

Where Pathfix fits#

Steps 2 to 8 repeat for every provider, with different endpoints, parameters and refresh rules each time. Pathfix OAuth handles the authorization flow, token storage, refresh and authenticated API passthrough across 350+ providers, using your own OAuth apps and credentials. You still build the feature: which API endpoints to call and what to do with the data.

See the documentation for how connections and API passthrough work.

Frequently asked questions#

Do server-side apps need PKCE?#

PKCE was designed for public clients but current security guidance recommends it for confidential clients too. It's cheap to add and protects against authorization code interception.

Can I use the implicit flow instead?#

The implicit flow is no longer recommended. Use Authorization Code with PKCE.

Where should the redirect URI point?#

To a backend route you control that can validate state and exchange the code server-side.