Implementing the OAuth flow

Prerequisites: Before implementing the OAuth flow, ensure you have your OAuth server configured, client credentials generated, JWKS endpoint accessible, and consistency key implementation chosen.

User -> Plaid -> Your /authorize -> User authenticates -> Your /token -> Plaid validates -> API access
       (redirect)                  (login + 2FA)         (code exchange)  (JWKS check)

The Authorization Code Grant follows a five-step process. This guide describes the OIDC flow. Plain OAuth 2.0 follows the same flow but without the ID token validation step.

Under regulatory requirements, the data recipient (or its platform) is responsible for obtaining user authorization. Plaid fulfills this obligation on behalf of apps via Plaid Link screens, divided as follows:

Data Provider hosts (your responsibility):

• Authentication screen - Users log in with their credentials on your domain.
• Account selection (optional) - If you are not using Plaid account selection, you may host account selection on your domain. This approach works but adds friction and limits the user experience for returning users, so Plaid does not recommend it for most integrations.

Plaid hosts (handled by Plaid Link, recommended):

• Data transparency messaging - Clear identification of which app is requesting access and what data will be shared.
• Account selection - User selects which accounts to share in Plaid Link after authenticating with you. Plaid recommends this model as it provides the best user experience for returning users.

The five steps:

1. Plaid redirects your user to authenticate
2. User logs in and authorizes access
3. You send Plaid an authorization code
4. Plaid exchanges the code for tokens
5. Plaid verifies the ID token and accesses your API

When a user starts linking their account, Plaid redirects them to your authorization endpoint (as defined in your well-known config). The redirect includes these query parameters:

https://auth.firstplatypus.com/oauth2/v1/authorize?response_type=code
&client_id=dc1fe34ae9e5e98147f2fd76060016a4
&redirect_uri=https%3A%2F%2Fcdn.plaid.com%2Flink%2Fv2%2Fstable%2Foauth.html
&state=v2.9f77edf0-a328-4501-9528-4a5f460cf770.0.0
&scope=openid%20offline_access%20accounts%20transactions
&prompt=login
&code_challenge=4dKRcTlKg7PbBxYokEH5gbfwfXcUdvDVYVdFZniVq4s
&code_challenge_method=S256

This page will be requested directly by the user's device.

At this step, the user authenticates with your system, typically username/password plus 2FA.

Plaid requires 2FA for Core Exchange connections. Users must complete a second authentication factor beyond username and password. 2FA aligns with industry security standards and reduces the risk of account takeover.

Use industry-standard 2FA methods such as one-time codes (SMS, email, authenticator apps), push notifications, biometric authentication, or hardware security keys. For mobile apps, biometric authentication provides the best user experience.

2FA communication requirements:

When sending 2FA prompts (SMS, email, push notification), the message must:

• Be clear about which app is requesting access - Include the app name from Plaid's authorization request
• Look legitimate - Use your standard templates and sender information to avoid appearing like phishing
• Be timely - Deliver within seconds of the authentication attempt

First Platypus Bank: Verify connection to Venmo.
Your code: 123456
If you didn't request this, contact us immediately.

Subject: Verify connection to Copilot

Hi [Name],

Venmo is requesting access to your First Platypus Bank account.

Your verification code: 123456

This code expires in 10 minutes.

If you didn't request this, please contact us immediately.

For mobile apps, enable App2App and biometric authentication. Your users will thank you.

If the user cancels, handle it as an error and send them back to Plaid with the right error code.

After the user successfully authenticates, generate a temporary authorization code and redirect the user's browser back to Plaid's redirect_uri. Include these query parameters:

https://cdn.plaid.com/link/v2/stable/oauth.html?code=1284918391
&state=eyJvYXV0aF9zdGF0ZV

Now, Plaid calls your token_endpoint to exchange the authorization code for tokens. This is a backend-to-backend call (no user involved), authenticated using the client ID and secret you issued.

The auth method comes from your well-known config. If you specified client_secret_basic, Plaid will send a basic auth header.

Request body format: application/x-www-form-urlencoded. Plaid sends these parameters:

curl --request POST 'https://auth.firstplatypusbank.com/oauth2/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header "Authorization: Basic YzVhNTI0NWIwNjJiZjg0MjBkMTFhYjQzNjFiMjhhMTU6clZYWU9vUVM0ckhVRzc5bl80OGFs" \
--data-raw '{
    "prompt": "login",
    "grant_type": "authorization_code",
    "code": "1284918391",
    "redirect_uri": "https://cdn.plaid.com/link/v2/stable/oauth.html",
    "scope": ["offline_access", "accounts"]
}'

Validate that the client_id, client_secret, code, and redirect_uri all match what you expect. If everything checks out, send Plaid the access_token, id_token, and refresh_token. All three are required to access your API.

{
  "access_token": "agstynmdygjdghabrgraeh...",
  "expires_in": 900,
  "id_token": "snsyjrhvjdtvyjvsgcegaethstj...",
  "refresh_token": "dhcsrtjsrgayvkdisfdgntshstu..."
}

After receiving the id_token, Plaid verifies its authenticity by fetching your JWKS from the jwks_uri in your .well-known config.

How verification works:

1. Fetch JWKS from your jwks_uri (Plaid caches this for speed).
2. Use the kid in the token header to find the right public key.
3. Verify the digital signature and claims (issuer, audience, expiration).
4. Extract the sub field (the user identifier).

User -> /authorize -> authenticates
-> /token -> returns tokens
-> Plaid fetches JWKS -> verifies ID token -> Done

Plaid now has everything needed to access your Core Exchange API on behalf of the user.

Access tokens expire. That's by design. When Plaid needs fresh data (e.g., balance checks before ACH transfers or transaction updates), it uses the refresh token to get a new access token. Same token_endpoint, different parameters.

curl --request POST 'https://auth.firstplatypusbank.com/oauth2/v1/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header "Authorization: Basic YzVhNTI0NWIwNjJiZjg0MjBkMTFhYjQzNjFiMjhhMTU6clZYWU9vUVM0ckhVRzc5bl80OGFs" \
--data-raw '{
    "grant_type": "refresh_token",
    "refresh_token": "dhcsrtjsrgayvkdisfdgntshstu..."
}'

Validate the grant_type and refresh_token, then respond with new tokens: access_token, id_token, and refresh_token.

Pro tip: Rotate the refresh token each time for better security (new token, new expiration). But if you need to reuse the same refresh token across multiple requests, that works too.

{
  "access_token": "lngarogglkcangasgabba...",
  "expires_in": 900,
  "id_token": "snsyjrhvjdtvyjvsgcegaethstj...",
  "refresh_token": "dhcsrtjsrgayvkdisfdgntshstu..."
}

See the full error reference below, along with the Troubleshooting Guide for detailed debugging.

OAuth errors fall into three categories, each handled differently. (Full details in RFC 6749 section 4.1.)

If the user cancels authentication or another error occurs (excluding redirect URI mismatches), redirect them back to Plaid with these parameters:

https://cdn.plaid.com/link/v2/stable/oauth.html?error=access_denied
&state=eyJvYXV0aF9zdGF0ZV

Errors during token exchange or refresh? Return HTTP 400 with an error field from the table below. Add error_description and error_uri if you want to help with debugging. (Details in RFC 6749 section 5.2.)

{
  "error": "invalid_grant",
  "error_description": "Authorization grant does not match redirect URI",
  "error_uri": "https://www.your-org.com/human-readable-error-info/"
}

When Plaid makes API requests with an access token, validate that it hasn't exceeded the lifetime you specified in expires_in during token issuance. Track when each token was issued and check that current_time - issue_time < expires_in.

If the access token has expired, send a 401 response with an error code of "602 not authorized". Plaid will automatically use the refresh token to request a new access token.