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
400with the error codeTOKEN_V4_REQUIRED, your application must use v4. Moving is required for your application, not optional.
What Changes
| v2 and v3 | v4 | |
|---|---|---|
| PKCE | Optional | Required, S256 only |
redirect_uri | Optional, must be on your allowlist | Required, https, exact match |
| Redirect from Yelp | code and state | code, state and iss |
| Access token lifetime | 7 days | 1 hour |
| Refresh token lifetime | 365 days by default | 90 days by default |
| New refresh token on every refresh | v2: no. v3: yes | Yes |
| 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.
- For each authorization request, generate a random
code_verifierof 43 to 128 characters, using onlyA-Z,a-z,0-9,-,.,_and~. - Set
code_challengeto the base64url-encoded SHA-256 hash of thecode_verifier, without padding. - Send
code_challengeandcode_challenge_method=S256on the authorization request. - Keep the
code_verifieron 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_urion 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_uriwhen 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
iss on the RedirectYelp 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 v3 | v4 | |
|---|---|---|
| Access token | 7 days | 1 hour |
| Refresh token | 365 days by default | 90 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_onandrefresh_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"
}
- Save the new refresh token before you use the new access token. If you lose it, the user needs to authorize your application again.
- Store the new refresh token every time, replacing the old one.
- 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 Code | Error Code | Meaning |
|---|---|---|
| 400 - Bad Request | invalid_request | A required parameter is missing or invalid. This includes a missing code_verifier. |
| 400 - Bad Request | invalid_grant | The 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 Request | invalid_client | The client_id or client_secret is missing or wrong. |
| 400 - Bad Request | invalid_scope | The request includes a scope your application isn't allowed to use. |
| 401 - Unauthorized | invalid_client | Client authentication failed after the request included an Authorization header. Send client_id and client_secret in the form body. |
| 429 - Too Many Requests | too_many_requests | You have exceeded the rate limit. Try again later. |
| 500 - Internal Server Error | server_error | Server error. If it happens on a refresh, retry straight away with the same refresh token. |
Update Checklist
- Authorization requests send an S256
code_challengeandcode_challenge_method=S256. - Authorization requests send an exact, registered
httpsredirect_uri, and the code exchange sends the same one. - Your redirect handler checks
stateandiss. - Code exchanges and refreshes call Get Access Token v4, with
client_idandclient_secretin the form body, and thecode_verifierfor 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_grantis not retried. - Error handling reads
erroranderror_descriptionfrom v4 responses.
Next Steps
- Authorization Code Workflow: the full flow, parameters and error pages.
- Refresh Tokens: rotation, the 60 second retry window and errors.
- Get Access Token v4: the endpoint reference.
Updated 20 minutes ago
