Authorize

Send the user's browser here to ask them to grant your application access. This is a page the user opens, not an API call.
The user signs in if needed, reviews the permissions, and chooses to continue or cancel. If they continue, Yelp redirects the browser back to your redirect_uri with an authorization code.
Exchange the code at Get Access Token v4 within 5 minutes. A code can be exchanged once.

Use the host that matches the user's account type:

  • biz.yelp.com/oauth2/authorize for business users. Request business scopes such as leads.
  • www.yelp.com/oauth2/authorize for consumers. Request consumer scopes: projects and project_actions.

A request can't mix business and consumer scopes, and a scope for the other account type is never granted.

Requirements for new integrations

  • PKCE with the S256 method: send code_challenge and code_challenge_method=S256, and send the matching code_verifier when you exchange the code.
  • redirect_uri is required, must use https, and 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.

Redirect back to your application

The redirect to your redirect_uri adds these query parameters:

  • code: the authorization code.
  • state: the value you sent, unchanged. Check it matches before you use the code.
  • iss: the issuer, https://api.yelp.com/oauth2/biz if the user approved on the business page or https://api.yelp.com/oauth2/consumer if they approved on the consumer page. Check it is the one you expect, as described in RFC 9207.

Errors

When a request is invalid, Yelp doesn't redirect to your redirect_uri and doesn't send an error parameter. The user sees an error page that tells them to contact the application the request came from. The page doesn't say what was wrong, so check these first if a user reports it:

  • code_challenge is missing, or code_challenge_method isn't S256.
  • redirect_uri is missing, isn't https, or isn't an exact match for a registered redirect URI.
  • response_type isn't code.
  • On www.yelp.com: scope is missing, or has a value that is unknown, isn't enabled for your application, or is a business scope, or it mixes business and consumer scopes.
  • On biz.yelp.com: scope includes a consumer scope that is enabled for your application. A scope that isn't enabled doesn't cause an error here. It's left out of the authorization instead (see scope below).
  • client_id is unknown, or the application is disabled.

If the user chooses Cancel, they are sent to yelp.com and your application isn't notified.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Query Params
string
required

The client ID Yelp assigned to your application.

string
enum
required

Must be code.

Allowed:
uri
required

Where Yelp sends the user after they approve. Must use https and exactly match a redirect URI registered for your application.

string
required

Space-separated scopes to request. Business page: for example leads. Consumer page: projects and project_actions.
Use only scopes enabled for your application, and only scopes for the host you send the user to.
On the business page, a scope that isn't enabled for your application is left out of the authorization, and the consent page only lists the scopes that remain. If none remain, the user can still approve, and the tokens have no scopes and can't call any Yelp API. Check scope in the Get Access Token v4 response to see what was granted. If no scopes were granted, the response has no scope field.

string

A random value your application generates for each request. Yelp returns it unchanged on the redirect. Use it to match the response to the request and to protect against cross-site request forgery.

string
required

PKCE code challenge (RFC 7636): the base64url-encoded SHA-256 hash of your code_verifier, without padding. Required for new integrations.

string
enum
required

Must be S256. Required for new integrations.

Allowed:
Response

redirect_uri with code, state (if you sent one) and iss added, for example
https://example.com/oauth/callback?code=AUTH_CODE&state=xyz&iss=https%3A%2F%2Fapi.yelp.com%2Foauth2%2Fconsumer.

Language
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
text/html