Authorization Code Workflow


Make sure you've read through the overview and the prerequisites


  1. Redirect the Business User to Yelp's authorization page
  2. After the user authorizes your application, an authorization code is returned to your application.
  3. Redeem the authorization code for an access token.
  4. Use the access token to make request on behalf of the business user.

Step 1: Redirect the Business User to Yelp's authorization page

Your application must redirect the business user’s browser to Yelp's authorization URL. This will be in the form of a GET request and you must provide the necessary GET parameters.

On the Yelp Login Page the business user will enter in their username and password to authorize the client to make requests for the specific oauth scopes on their behalf.



The login page sent back to the business user contains an X-Frame-Option SAMEORIGIN header. This prevents the login page from being embedded in a non-Yelp frame.



client_idRequiredID assigned by Yelp for the third-party system that will make user-authorized requests to Yelp.
redirect_uriOptionalAn endpoint provided by the client. After the user has entered their credentials, Yelp will redirect to this endpoint, submitting either the authorization code or an error message. If this parameters is not supplied, the default redirect URI submitted during client registration will be used.
response_typeRequiredA string denoting the type of response. In the case of requesting an authorization code, this value will be code.
scopeRequiredA space delimited list of actions that the business user is authorizing the client to perform.

leads - enables reading leads and responding to them.
r2r - enables respond to review permission.
r2r_get_businesses - enables the ability to retrieve a list of businesses that the business owner has "claimed" aka businesses that this user can respond to reviews for.
r2r_business_owner - enables the ability to retrieve information about the business owner like username and profile photo.

Yelp must enable your application for each scope, do not request scopes you don't have access to.
stateRequiredA unique string generated by the client to maintain state between the request and the callback. Used to prevent CSRF

Request Template

The user will be shown a confirmation dialog naming your application and the permissions(scopes) you requested:


Example business user dialog on


Once the business user’s credentials are validated and they have authorized your application, an authorization code is sent back to the client’s redirect URI.

Parameter NameDescription
codeA unique code that will be used by the client to redeem an access token.
stateThe state passed into the initial request. Verify this is the same as in the request to Yelp to prevent CSRF

Request Template

Step 2: Redeem the authorization code for an access token

The Authorization Code expires in 5 minutes so the client should redeem the authorization code for an access token immediately. You should verify that the state parameter matches the parameter from the original authorization request to prevent possible CSRF.

Using the authorization code assigned for that business user, the Get Access Token endpoint will send back an access token. The Access Token expires in 7 days. When it expires the client should refresh the token.

Endpoint documentation:

Step 3: Use the access token to make request on behalf of the business user.

Once you have the access token you can start making API calls to all oauth secured Yelp APIs which are included in the scopes you have requested. You must include the access token in the Authorization header of the HTTP call.

Request Template

curl -X GET -H 'Authorization: Bearer <access_token>'

Example: Retrieve businesses associated with access token

You can retrieve a list of all open businesses associated with a specific business user's access token.

Endpoint documentation:

Step 4: Refresh Access Token

Revoke Access Token

The authorization server responds with HTTP status code 200 if the token has been revoked successfully or if the client submitted an invalid token.

Endpoint documentation:

Token Lifetimes

  • Authorization Code: 5 minutes
  • Access Token: 7 days
  • Refresh Token: 365 days

Error Scenarios

For the following error scenarios, Yelp will send back an error code to the redirect URI. If a state was provided in the the original request, it will be included in the error response.


If the client_id is not submitted or invalid, or an invalid redirect_uri is submitted, Yelp will display an error message to the business user as there is no way of notifying the client without a client_id and a valid redirect_uri.

If no client_id is provided, a 404 Not Found will be returned.

Error CodeDescriptionHTTP Code
invalid_requestThe request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed.400 - Bad Request
access_deniedThe state supplied in the request is not unique/has been used before.403 - Forbidden
invalid_scopeThe request is unauthorized for the given scope.400 - Bad Request
unsupported_response_typeUnsupported response type.400 - Bad Request
server_errorServer error.500 - Internal Server Error

Error Response Template:

What’s Next