Authorization Code Workflow
Make sure you've read through the overview and the prerequisites
Workflow
- Redirect the Business User to Yelp's authorization page
- After the user authorizes your application, an authorization code is returned to your application.
- Redeem the authorization code for an access token.
- 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.
Note
The login page sent back to the business user contains an
X-Frame-Option SAMEORIGINheader. This prevents the login page from being embedded in a non-Yelp frame.
GET https://biz.yelp.com/oauth2/authorize
Parameters
| Parameter | Required | Description |
|---|---|---|
client_id | Required | ID assigned by Yelp for the third-party system that will make user-authorized requests to Yelp. |
redirect_uri | Optional | An 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_type | Required | A string denoting the type of response. In the case of requesting an authorization code, this value will be code. |
scope | Required | A 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. |
state | Required | A unique string generated by the client to maintain state between the request and the callback. Used to prevent CSRF |
Request Template
https://biz.yelp.com/oauth2/authorize?client_id=itk2LQ1r9e88jEjKiGae1w&redirect_uri=http://www.example.com/redirect_endpoint&response_type=code&scope=r2r&state=some_unique_string
The user will be shown a confirmation dialog naming your application and the permissions(scopes) you requested:
Example business user dialog on yelp.com
Response
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 Name | Description |
|---|---|
| code | A unique code that will be used by the client to redeem an access token. |
| state | The state passed into the initial request. Verify this is the same as in the request to Yelp to prevent CSRF |
Request Template
https://www.example.com/redirect_endpoint?code=54321&state=some_unique_string
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:
docs.developer.yelp.comStep 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 https://partner-api.yelp.com/token/v1/businesses -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_uriis submitted, Yelp will display an error message to the business user as there is no way of notifying the client without aclient_idand a validredirect_uri.
If no client_id is provided, a 404 Not Found will be returned.
| Error Code | Description | HTTP Code |
|---|---|---|
| invalid_request | The 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_denied | The state supplied in the request is not unique/has been used before. | 403 - Forbidden |
| invalid_scope | The request is unauthorized for the given scope. | 400 - Bad Request |
| unsupported_response_type | Unsupported response type. | 400 - Bad Request |
| server_error | Server error. | 500 - Internal Server Error |
Error Response Template:
http://www.example.com/redirect_endpoint?error=invalid_request&state=some_state_you_passed_in
Updated about 2 years ago