Requesting credentials

API credentials are obtained by using the OAuth 2.0 implicit authorization grant. You must send the user's client (browser) to the authorization URI. This is generally accomplished by providing the authorization URI as a link on a webpage.

The user will then have the option to accept or deny your application, and to deny any of the scopes you requested (except for public.) If the user accepts your application, they are redirected to your application's callback URI along with an access token and some additional parameters. Your application must validate that the state parameter matches the original value. If the state does not match, your application must not attempt to use the access token.

response_type string Must be token.
client_id string Your application's client ID.
redirect_uri string Your application's callback URI.
scope string An optional space-separated list of scopes that you want to access.
state string An optional value used to prevent CSRF attacks. See RFC 6749 §10.12.

GET /oauth2/authorize?response_type=token&client_id=Y2XPZW50Q31A
    &scope=private&state=cmFuZG9t HTTP/1.1
Content-Type: application/x-www-form-urlencoded


HTTP/1.1 302 Found

Response types

200 OK

The HTTP status code 200 OK is returned for all successful GET, HEAD, PUT and PATCH requests. The body of the HTTP response contains the requested resource.

When the requested resource is a collection of items, an RFC 5988 Link header will be returned in the HTTP response. This header contains the URIs of the next and previous items in the collection. It is used to facilitate navigation.

201 Created

The HTTP status code 201 Created is returned for all successful POST requests. The body of the HTTP response contains the newly created resource.

When a resource is created successfully, an RFC 2616 Location header will be returned in the HTTP response. This header contains the URI of the resource that was created.

204 No Content

The HTTP status code 204 No Content is returned for all successful DELETE requests. The body of the HTTP response is empty in this case.

Supported scopes


The public scope grants access to public resources.


The private scope grants access to resources that are owned by the authenticated user.


The create scope grants permission to create new resources.


The edit scope grants permission to modify resources.


The delete scope grants permission to delete resources.


The users scope grants access to user resources. This includes users and user profiles.


The orders scope grants access to order resources. This includes customers, payments, orders, line items and order attributes.

Private endpoints

Private endpoints refer to resources that are owned by a specific user. The username of the resource owner must be specified in the request URI. Requests to private endpoints must be authenticated.

If the authenticated user is the resource owner, the client may use the private scope to access that resource. The special username me refers to the authenticated user. For example, a client which has only been granted private scope could make a GET request to /users/me/orders.json to retrieve the current user's order history.

Add Feedback