OAuth

The Big Cartel API uses OAuth 2.0 to provide your application with access to an account without the need for sharing or storing passwords. To do this, you’ll redirect your user to Big Cartel, they’ll login and see a page explaining exactly who wants access and what they’ll have access to. After allowing or denying your request, they’ll be sent back to your site.

Authorization page

Invite-only! To use OAuth you’ll first need to request an invite.

Using an OAuth library

Since OAuth is a common and open protocol, there are already a number of projects that make it easy to use without much work on your part.

  1. Grab an OAuth library.
  2. Configure it with your client_id, client_secret, and redirect_uri.
  3. Tell it to use https://my.bigcartel.com/oauth/authorize to request authorization and https://api.bigcartel.com/oauth/token to get access tokens.

That’s it! You can now use your access_token to make API calls.

OAuth from scratch

If you’re the type that likes to have full control over your code, and don’t mind reinventing a wheel now and then, you can create your own OAuth integration.

1. Redirect the user to Big Cartel to request access

To connect your application to a Big Cartel account, redirect them to our authorization page which will prompt them to give you access to their account.

GET https://my.bigcartel.com/oauth/authorize
Parameters
Name Type Required Description
client_id string true Your unique client identifier from your application settings.
response_type string false The only option right now is code.
state string false An arbitrary value, sent back with each response (useful for identifying users on your end).
redirect_uri string false URL where your users are sent after authorization.

2. Big Cartel redirects back to your site

If the user accepts your request, they’ll be redirected to your redirect_uri with a temporary code in a code parameter as well as the state you may have provided in the previous step in a state parameter. If the states don’t match what you expect, the request has been created by a third party and the process should be aborted.

If the user denies your request, they’ll be redirected to your redirect_uri with the an error parameter containing the appropriate error code.

3. Exchange the temporary code for an access token

You’ll now need to make a request to trade the code you received for an access_token.

POST https://api.bigcartel.com/oauth/token
Parameters
Name Type Required Description
client_id string true Your unique client identifier from your application settings.
client_secret string true Your unique and private client secret from your application settings.
code string true The code parameter you received in the previous step.
redirect_uri string false URL where your users are sent after authorization.
Response

If successful, we’ll return a JSON response in the following format.

{
  "access_token":"YOUR-ACCESS-TOKEN",
  "token_type":"bearer",
  "account_id":12345
}

That’s it! You can now use your access_token to make API calls.

Making API calls

Once you’ve obtained an access_token for an account, you can use it in the Authorization header of all of your requests.

Authorization: Bearer YOUR-ACCESS-TOKEN

For example, in curl you can set the Authorization header like this:

curl -H "Authorization: Bearer YOUR-ACCESS-TOKEN" https://api.bigcartel.com/accounts/12345

Errors

If at any point there are problems or invalid parameters in your request, we’ll send back an error code in the following format.

{
  "error":"client_secret_invalid"
}

Possible errors include:

Name Description
access_denied The user has denied access to their account.
invalid_client_id The client_id you specified is invalid.
invalid_client_secret The client_secret you specified is invalid.
invalid_redirect_uri The redirect_uri you specified is invalid.
invalid_response_type Your request’s response type is invalid.