Scopes

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](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, /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