Scopes determine what data an app has access to. By limiting what sort of data your API client is allowed to access to the bare minimum, you can make users feel safer with using your application.
You set the default when creating your API client, and can further restrict them on a per-token basis when using the OAuth authentication method.
Using Scopes
Nearly every route in the API has an associated scope required to use it. If your client or (Access Token in the case of OAuth) doesn’t have the required scope, you’ll be given an error with the 403 Forbidden response code.
There are 4 scopes with both read and write access available for each. Write access implies read access, so there’s no reason to duplicate them.
All clients
Read only Can get the API landing page (/), /help, and /data/* routes. Regardless of scope, all clients can do these things.
Account
Read Can read from /account/*, /events/*, /ext_accounts/*, and /users/{email}/
Write Can write to /events/*, /ext_accounts/*
Public
Read Can read from /ranks, /reviews, /reports/ratings, /featured, and /products operations without knowing account products.
Write Can write to /reviews/*/response
Private
Read Can read from /reports/ads, /reports/adspend, /reports/sales, /archive, and /payments
Write No Additional Access
Products
Read Can GET a list of all products products in the account using /products/mine or /ext_accounts/{id}/products. Products become available in the /users/*routes as well.
Write Can PUT to /products/{product_id} to change the active and hidden fields
Whenever you create an API Client (that is to say get a Client Key and Secret), you’ll be prompted to select a default scope. All requests using HTTP Authentication will use that scope no matter what.
When using OAuth you can further limit the scope to make it more strict than what you initially specified. You use the X-OAuth-Scope header to do this, and pass it a comma separated list of scopes. Scopes are represented by the name followed by a colon and whether you’d like read or write access.
For example, to write to products and read from private data and the account I’d set the header like this:
X-OAuth-Scope: products:write, private:read, account:read