Moving to OAuth 2.1 and Token v4

šŸ“˜

Audience

This guide is for Partners who already use Yelp OAuth with Get Access Token v2 or v3, or whose requests return TOKEN_V4_REQUIRED. If you're building a new integration, start with the Authorization Code Workflow, which already describes the steps below.

Yelp's OAuth follows OAuth 2.1. The token endpoint is Get Access Token v4 (POST https://api.yelp.com/oauth2/token/v4), and the authorization step is stricter. This guide lists what changes from v2 and v3, so you can update your application.

🚧

TOKEN_V4_REQUIRED

If v2 or v3 returns 400 with the error code TOKEN_V4_REQUIRED, your application must use v4. Moving is required for your application, not optional.

What Changes

v2 and v3v4
PKCEOptionalRequired, S256 only
redirect_uriOptional, must be on your allowlistRequired, https, exact match
Redirect from Yelpcode and statecode, state and iss
Access token lifetime7 days1 hour
Refresh token lifetime365 days by default90 days by default
New refresh token on every refreshv2: no. v3: yesYes
Error format{"error": {"code": …, "description": …}}{"error": "…", "error_description": "…"}

The sections below go through each change.

Step 1: Add PKCE

PKCE ties an authorization code to the application that asked for it, so a stolen code is useless to anyone else. v4 requires it, with the S256 method only.

  1. For each authorization request, generate a random code_verifier of 43 to 128 characters, using only A-Z, a-z, 0-9, -, ., _ and ~.
  2. Set code_challenge to the base64url-encoded SHA-256 hash of the code_verifier, without padding.
  3. Send code_challenge and code_challenge_method=S256 on the authorization request.
  4. Keep the code_verifier on your server, and send it when you redeem the code. Don't send it in the authorization request.
import base64
import hashlib
import secrets

code_verifier = secrets.token_urlsafe(64)
code_challenge = (
    base64.urlsafe_b64encode(hashlib.sha256(code_verifier.encode("ascii")).digest())
    .rstrip(b"=")
    .decode("ascii")
)

An authorization request without an S256 code_challenge shows the user an error page, and a code exchange without the matching code_verifier returns invalid_request or invalid_grant.

Step 2: Use Exact HTTPS Redirect URIs

On v2 and v3, redirect_uri can be left out, and the one you send only has to be on your allowlist. Now:

  • Send redirect_uri on every authorization request.
  • It must use https.
  • It must exactly match a redirect URI registered for your application. Yelp doesn't ignore a trailing slash, match a prefix, or fall back to a default.
  • Send the same redirect_uri when you redeem the code.

If the redirect URI doesn't match, the user sees an error page instead of being sent back to your application. To register or change a redirect URI, contact your Yelp relationship manager.

Step 3: Check iss on the Redirect

Yelp now adds an iss parameter to the redirect, next to code and state:

https://www.example.com/redirect_endpoint?code=54321&state=some_unique_string&iss=https%3A%2F%2Fapi.yelp.com%2Foauth2%2Fbiz

iss names the issuer of the response. It is https://api.yelp.com/oauth2/biz if the user authorized on biz.yelp.com, and https://api.yelp.com/oauth2/consumer if they authorized on www.yelp.com. Before you use the code, check that iss is the issuer for the authorization page you sent the user to. If it isn't, discard the response. This protects your application from a response meant for a different authorization server. See RFC 9207.

Step 4: Redeem Codes on Get Access Token v4

Send the code to Get Access Token v4 instead of v2 or v3, with the code_verifier and redirect_uri. Send client_id and client_secret in the form body. v4 doesn't accept them in an Authorization header.

POST /oauth2/token/v4 HTTP/1.1
Host: api.yelp.com
Content-Type: application/x-www-form-urlencoded

client_id={client_id}&
client_secret={client_secret}&
grant_type=authorization_code&
code={code}&
redirect_uri={redirect_uri}&
code_verifier={code_verifier}

The authorization code expires in 5 minutes and can be used once. If it's rejected, start again from the authorization request with a new code challenge.

Step 5: Plan for Shorter Token Lifetimes

v2 and v3v4
Access token7 days1 hour
Refresh token365 days by default90 days by default

Moving to v4 means shorter tokens:

  • Tokens you already hold move to the v4 lifetimes the first time you refresh them on v4. Until then, an existing refresh token keeps the expiry it was issued with. The first v4 refresh returns an access token that lasts 1 hour and a refresh token that lasts 90 days.
  • Refresh when the access token expires. Don't wait for an API call to fail, and don't hard-code the lifetimes. Each response has expires_on and refresh_token_expires_on.
  • If you have an agreement with Yelp for longer-lived refresh tokens, it doesn't carry over to v4 automatically. Contact your Yelp relationship manager before you move to v4.

A user whose refresh token has expired needs to authorize your application again.

Step 6: Store Every New Refresh Token

On v4, every refresh rotates the refresh token: the response includes a new refresh token, and the one you sent stops working.

{
  "access_token": "<128_character_long_string>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "expires_on": "2026-11-10T20:00:00+00:00",
  "refresh_token": "<128_character_long_string>",
  "refresh_token_expires_in": 7776000,
  "refresh_token_expires_on": "2027-02-08T19:00:00+00:00"
}
  1. Save the new refresh token before you use the new access token. If you lose it, the user needs to authorize your application again.
  2. Store the new refresh token every time, replacing the old one.
  3. Send one refresh at a time for each user, so you always know which refresh token is the current one.

If your application is built around v2, where the refresh token never changes, this is the change most likely to break it. Look for any place that reads the refresh token once and keeps it.

Retries and Reuse Detection

ā—ļø

Don't reuse a refresh token more than 60 seconds after refreshing with it

Yelp treats this as a sign that the token was stolen, and revokes the newest refresh token issued from it. The user then needs to authorize your application again.

You can retry for 60 seconds. If a refresh fails before you get the response (a timeout or a dropped connection, for example), send the same request again with the same refresh token. Within 60 seconds of the first request succeeding, Yelp returns the same new access token and refresh token instead of an error.

After 60 seconds, a reused refresh token is treated as stolen (RFC 9700 §4.14). The request fails with invalid_grant, and Yelp also revokes the newest refresh token issued from it, even if you stored it correctly. Access tokens are not revoked.

To avoid this:

  • Retry a failed refresh straight away, not on a delayed job.
  • Don't keep old refresh tokens anywhere they could be sent again, such as a cache or a retry queue.
  • If a refresh returns invalid_grant, stop retrying. Discard the user's tokens and send them through the Authorization Code Workflow again.

The Refresh Tokens guide has the full request and error list.

Step 7: Handle OAuth 2.1 Errors

v2 and v3 return errors in Yelp's format, which is used by other Yelp APIs too:

{
  "error": {
    "code": "INVALID_GRANT",
    "description": "…"
  }
}

v4 returns a flat OAuth 2.1 error with a lowercase error code and an error_description:

{
  "error": "invalid_grant",
  "error_description": "Invalid token"
}

Update any code that reads error.code or error.description. Read error and error_description from v4 responses. TOKEN_V4_REQUIRED is the exception: it's returned by v2 and v3, so it uses the Yelp format.

HTTP CodeError CodeMeaning
400 - Bad Requestinvalid_requestA required parameter is missing or invalid. This includes a missing code_verifier.
400 - Bad Requestinvalid_grantThe code or refresh token is unknown, expired, revoked or already used, the code_verifier doesn't match, or the redirect_uri doesn't match.
400 - Bad Requestinvalid_clientThe client_id or client_secret is missing or wrong.
400 - Bad Requestinvalid_scopeThe request includes a scope your application isn't allowed to use.
401 - Unauthorizedinvalid_clientClient authentication failed after the request included an Authorization header. Send client_id and client_secret in the form body.
429 - Too Many Requeststoo_many_requestsYou have exceeded the rate limit. Try again later.
500 - Internal Server Errorserver_errorServer error. If it happens on a refresh, retry straight away with the same refresh token.

Update Checklist

  • Authorization requests send an S256 code_challenge and code_challenge_method=S256.
  • Authorization requests send an exact, registered https redirect_uri, and the code exchange sends the same one.
  • Your redirect handler checks state and iss.
  • Code exchanges and refreshes call Get Access Token v4, with client_id and client_secret in the form body, and the code_verifier for code exchanges.
  • Your application refreshes when the access token expires and doesn't assume 7 days or 365 days.
  • Every refresh saves the new refresh token before the new access token is used.
  • Retries of a failed refresh happen straight away, and a refresh that returns invalid_grant is not retried.
  • Error handling reads error and error_description from v4 responses.

Next Steps


Did this page help you?