Scopes
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, /features, and /products operations without knowing account products
- write
- No Additional Access
private
- read
- Can read from /ads, /sales, /archive, and /payments. NOTE: some private routes return products as part of their representation.
- write
- No Additional Access
products
- read
- Can GET account’s products: /products/mine and /ext_accounts/{id}/products. Products become available in the /users/* routes as well. NOTE: some routes with private scope return products as part of their representation.
- write
- Can PUT to /products/{product_id} to change active/hidden status.
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