{"_id":"56196204fa2a6d0d002a1352","project":"556cd8aec14029190092d292","version":{"_id":"556cd8aec14029190092d295","__v":14,"project":"556cd8aec14029190092d292","createdAt":"2015-06-01T22:11:58.756Z","releaseDate":"2015-06-01T22:11:58.756Z","categories":["556cd8afc14029190092d296","55ca5a55241e790d004f47ea","55dc9fdb4f535537007da1b2","55dc9fdfc755b63700dc843c","55fdb08c4bebdf17004130d4","560ef4c2a36c610d00e7013e","5613db296a092921004c30c2","56156581dc8aea0d002475e8","56169d1ee98f5517005627a8","5622fde7de7dc01700c6dd5f","56cf75f3336aa60b0086a495","5818f3c02093901b00bcf91a","582f7ff88ea0800f0035639a","583f30c110448a2500dd990f"],"is_deprecated":false,"is_hidden":false,"is_beta":false,"is_stable":true,"codename":"","version_clean":"1.0.0","version":"1.0"},"user":"556cbb50c14029190092d20f","parentDoc":null,"category":{"_id":"5622fde7de7dc01700c6dd5f","pages":["5622fe48d51d480d0064fc77","5623104906481c0d00e53162","56231066de7dc01700c6dd65","5627f69388948617002a0996"],"project":"556cd8aec14029190092d292","__v":4,"version":"556cd8aec14029190092d295","sync":{"url":"","isSync":false},"reference":false,"createdAt":"2015-10-18T02:03:19.875Z","from_sync":false,"order":3,"slug":"authentication-and-authorization","title":"Authentication and Authorization"},"__v":33,"updates":["593e9b0f1d433b000f10f15b"],"next":{"pages":[],"description":""},"createdAt":"2015-10-10T19:07:48.936Z","link_external":false,"link_url":"","githubsync":"","sync_unique":"","hidden":false,"api":{"settings":"","results":{"codes":[]},"auth":"required","params":[],"url":""},"isReference":false,"order":3,"body":"## Is this the right flow for you?\n\nBefore you get started, let's make sure this is the right approach for you. [Learn more at: How should I authenticate?](doc:how-should-i-authenticate) \n\n## Let's get started\n\nOAuth2 is a protocol that lets external apps request authorization from Reverb to perform actions on behalf of a user without storing the user's password on the app. Users can allow apps to perform specific types of operations (for example, read vs update data), and can revoke access at any time, making this a secure and convenient way to integrate.\n\n**All apps need to be [registered first](https://reverb.com/apps/new)**\n\nA registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared.\n\n## OAuth2 is Standard - Don't roll your own implementation\n\nThe flow below outlines the specifics of what happens, but you should be able to take an off the shelf oauth2 library for your platform. Here are a few existing ones: \n\n* [Ruby](https://github.com/intridea/oauth2)\n* [PHP](https://github.com/fkooman/php-oauth-client)\n* [.NET](https://github.com/titarenko/OAuth2)\n\n[See the full list of available oauth2 clients](http://oauth.net/2/#client-libraries)\n\nThe code below will show the basic actions required to complete the OAuth2 Authorization Code Flow which involves obtaining a code and then posting it back to Reverb to get a Bearer Token. \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"1. Redirect users to Reverb to request access.\"\n}\n[/block]\nYour app should provide a button with the title \"Login with Reverb.com\" or similar. This button should link to the following url:\n\n```\nhttps://reverb.com/oauth/authorize?client_id=[your-client-id]&redirect_uri=[your-callback-url]&response_type=code&scope=read_listings+write_listings\"\n```\n\nExplanation of params:\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"client_id\",\n    \"h-0\": \"Param Name\",\n    \"h-1\": \"Type\",\n    \"h-2\": \"Description\",\n    \"0-1\": \"string\",\n    \"0-2\": \"**Required**. The client ID is a unique id assigned to your application when you register it with Reverb. View your ClientID at https://reverb.com/my/api_settings by clicking the details link for your app.\",\n    \"1-0\": \"redirect_uri\",\n    \"1-1\": \"string\",\n    \"1-2\": \"**Required**. The URL where Reverb will redirect once the user authorizes your app. This should look something like https://yourdomain.com/auth/reverb/success\",\n    \"2-0\": \"scope\",\n    \"2-1\": \"string\",\n    \"2-2\": \"Optional. A list of oauth scopes that your application requires on the user's behalf. The list is delimited by spaces, which is URI encoded as `+`. For example, an app that wants to read the user's listings and update them should use the scope: `read_listings+update_listings`. By default you will only get read access to the user's information.\\n\\n[List of all OAuth Scopes](doc:oauth-scopes)\",\n    \"3-0\": \"response_type\",\n    \"3-1\": \"string\",\n    \"3-2\": \"**Required**. Should be set to `code`. No other values are supported.\",\n    \"4-0\": \"state\",\n    \"4-1\": \"string\",\n    \"4-2\": \"Optional. This parameter will be delivered back to you during the redirect. You should use this to set a randomly generated unguessable string so that you can validate the request for additional security in step 3.\"\n  },\n  \"cols\": 3,\n  \"rows\": 5\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"2. User authorizes application\"\n}\n[/block]\nThe user will be presented with a screen that looks similar to this:\n[block:image]\n{\n  \"images\": [\n    {\n      \"image\": [\n        \"https://files.readme.io/5kFGgdfROmpGfuauNqvG_OAuth_authorize_required.png\",\n        \"OAuth_authorize_required.png\",\n        \"1284\",\n        \"634\",\n        \"#5bb35c\",\n        \"\"\n      ]\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"3. User is redirected back to your redirect_uri with a code\"\n}\n[/block]\nThe user's browser will be redirected back to your site with a temporary `code`. The url will look something like this:\n```\nhttps://yoursite.com/auth/reverb/success?code=12345abcdefg&state=yourstate\n```\n\nIf you supplied a `state` parameter in step 1, this is a good time to validate that the state you got back is the same as you requested. If it's not, the request originated with a third party and should be ignored. [Read more about CSRF protection with the state parameter.](http://www.twobotechnologies.com/blog/2014/02/importance-of-state-in-oauth2.html) \n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"4. You request a token from Reverb\"\n}\n[/block]\nTo request a token from reverb, you will POST to the url `https://reverb.com/oauth/token` with the following parameters.\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -XPOST https://reverb.com/oauth/token?client_id=[...]&client_secret=[...]&code=[...]&grant_type=authorization_code&redirect_uri=[...]\\n\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]\nThe response will contain an access token:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"{\\\"access_token\\\":\\\"7ef5a3d9a01290e61449542e2033f76a84236b7902dfe8dee9278b73eee71db4\\\",\\\"token_type\\\":\\\"bearer\\\",\\\"scope\\\":\\\"update_listings read\\\",\\\"created_at\\\":1444505942}%\",\n      \"language\": \"json\"\n    }\n  ]\n}\n[/block]\n\n[block:api-header]\n{\n  \"type\": \"basic\",\n  \"title\": \"5. Use the token in subsequent requests to Reverb\"\n}\n[/block]\nNow you should set your client's headers to contain the given token in the `Authorization` header in every API request you make, using the OAuth Bearer token format:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -XGET https://api.reverb.com/api/some/thing -H \\\"Authorization: Bearer 7ef5a3d9a01290e61449542e2033f76a84236b7902dfe8dee9278b73eee71db4\\\"\\n\",\n      \"language\": \"curl\"\n    }\n  ]\n}\n[/block]","excerpt":"","slug":"build-a-multi-user-app-with-oauth","type":"basic","title":"Apps for multiple users (OAuth2 Access Code Flow)"}

Testing on Sandbox

About The API

Reverb App Store

Authentication and Authorization

How To...

More Integrations

Troubleshooting

Apps for multiple users (OAuth2 Access Code Flow)

## Is this the right flow for you? Before you get started, let's make sure this is the right approach for you. [Learn more at: How should I authenticate?](doc:how-should-i-authenticate) ## Let's get started OAuth2 is a protocol that lets external apps request authorization from Reverb to perform actions on behalf of a user without storing the user's password on the app. Users can allow apps to perform specific types of operations (for example, read vs update data), and can revoke access at any time, making this a secure and convenient way to integrate. **All apps need to be [registered first](https://reverb.com/apps/new)** A registered OAuth application is assigned a unique Client ID and Client Secret. The Client Secret should not be shared. ## OAuth2 is Standard - Don't roll your own implementation The flow below outlines the specifics of what happens, but you should be able to take an off the shelf oauth2 library for your platform. Here are a few existing ones: * [Ruby](https://github.com/intridea/oauth2) * [PHP](https://github.com/fkooman/php-oauth-client) * [.NET](https://github.com/titarenko/OAuth2) [See the full list of available oauth2 clients](http://oauth.net/2/#client-libraries) The code below will show the basic actions required to complete the OAuth2 Authorization Code Flow which involves obtaining a code and then posting it back to Reverb to get a Bearer Token. [block:api-header] { "type": "basic", "title": "1. Redirect users to Reverb to request access." } [/block] Your app should provide a button with the title "Login with Reverb.com" or similar. This button should link to the following url: ``` https://reverb.com/oauth/authorize?client_id=[your-client-id]&redirect_uri=[your-callback-url]&response_type=code&scope=read_listings+write_listings" ``` Explanation of params: [block:parameters] { "data": { "0-0": "client_id", "h-0": "Param Name", "h-1": "Type", "h-2": "Description", "0-1": "string", "0-2": "**Required**. The client ID is a unique id assigned to your application when you register it with Reverb. View your ClientID at https://reverb.com/my/api_settings by clicking the details link for your app.", "1-0": "redirect_uri", "1-1": "string", "1-2": "**Required**. The URL where Reverb will redirect once the user authorizes your app. This should look something like https://yourdomain.com/auth/reverb/success", "2-0": "scope", "2-1": "string", "2-2": "Optional. A list of oauth scopes that your application requires on the user's behalf. The list is delimited by spaces, which is URI encoded as `+`. For example, an app that wants to read the user's listings and update them should use the scope: `read_listings+update_listings`. By default you will only get read access to the user's information.\n\n[List of all OAuth Scopes](doc:oauth-scopes)", "3-0": "response_type", "3-1": "string", "3-2": "**Required**. Should be set to `code`. No other values are supported.", "4-0": "state", "4-1": "string", "4-2": "Optional. This parameter will be delivered back to you during the redirect. You should use this to set a randomly generated unguessable string so that you can validate the request for additional security in step 3." }, "cols": 3, "rows": 5 } [/block] [block:api-header] { "type": "basic", "title": "2. User authorizes application" } [/block] The user will be presented with a screen that looks similar to this: [block:image] { "images": [ { "image": [ "https://files.readme.io/5kFGgdfROmpGfuauNqvG_OAuth_authorize_required.png", "OAuth_authorize_required.png", "1284", "634", "#5bb35c", "" ] } ] } [/block] [block:api-header] { "type": "basic", "title": "3. User is redirected back to your redirect_uri with a code" } [/block] The user's browser will be redirected back to your site with a temporary `code`. The url will look something like this: ``` https://yoursite.com/auth/reverb/success?code=12345abcdefg&state=yourstate ``` If you supplied a `state` parameter in step 1, this is a good time to validate that the state you got back is the same as you requested. If it's not, the request originated with a third party and should be ignored. [Read more about CSRF protection with the state parameter.](http://www.twobotechnologies.com/blog/2014/02/importance-of-state-in-oauth2.html) [block:api-header] { "type": "basic", "title": "4. You request a token from Reverb" } [/block] To request a token from reverb, you will POST to the url `https://reverb.com/oauth/token` with the following parameters. [block:code] { "codes": [ { "code": "curl -XPOST https://reverb.com/oauth/token?client_id=[...]&client_secret=[...]&code=[...]&grant_type=authorization_code&redirect_uri=[...]\n", "language": "curl" } ] } [/block] The response will contain an access token: [block:code] { "codes": [ { "code": "{\"access_token\":\"7ef5a3d9a01290e61449542e2033f76a84236b7902dfe8dee9278b73eee71db4\",\"token_type\":\"bearer\",\"scope\":\"update_listings read\",\"created_at\":1444505942}%", "language": "json" } ] } [/block] [block:api-header] { "type": "basic", "title": "5. Use the token in subsequent requests to Reverb" } [/block] Now you should set your client's headers to contain the given token in the `Authorization` header in every API request you make, using the OAuth Bearer token format: [block:code] { "codes": [ { "code": "curl -XGET https://api.reverb.com/api/some/thing -H \"Authorization: Bearer 7ef5a3d9a01290e61449542e2033f76a84236b7902dfe8dee9278b73eee71db4\"\n", "language": "curl" } ] } [/block]