Here is a step-by-step guide on how to make your first request to the Sell API. We will provide your authentication details by returning a token using your login credentials. We will make this request through the Users API using the Retrieve an authenticating user endpoint.

In this tutorial, we use a simplified application workflow to authenticate - Single-User workflow.

Be sure to substitute your access token into these requests.

Plan

  1. Generate an access token
  2. Make an API call

1. Generate an access token

In order to create an access token, you need to have Account Management Privileges.

All of your API requests to our resource servers must be authenticated and include a valid access token. To make your first successful request, you will need those credentials.

You can have multiple Personal Access Tokens (PATs). Each one can be easily revoked and recreated.

To get your Personal Access Token:

  1. Sign into Sell using your credentials and navigate to Integrations > OAuth.
  2. In the Access Tokens tab, click the + Add User Token button.
  3. Fill in the Description field and click the Save button.

At this point you should see a modal window with your newly generated access token.

  1. From the modal window, copy the access token and store it for further use, as it will be required during your first call.

Once the modal window is closed, it is impossible to retrieve your access token. If you cannot find your token information, you will need to generate a new token.


2. Make an API call

At this point, we are ready to make a request. We have a valid access token and we know the endpoint we are going to hit in order to retrieve your authenticating user:

https://api.getbase.com/v2/users/self

All requests to the API must be made over SSL (https:// not http://).

To authenticate to the Sell API, we will use the standard Authorization header, using the Bearer authentication schema to transmit the access token. Details on authenticating to our resource servers can be found in the Accessing Protected Resources article. We use the following syntax:

Authorization: Bearer $ACCESS_TOKEN

Our API is understood by any off-the-shelf HTTP client, but in this case we will use the curl command line tool.

The way to do this with curl is to use:

  • the -X flag, which specifies a custom request method. In our case it is the GET method ( -X GET ).
  • the -H flag, which is used to include an extra header in the request when sending HTTP to a server. In our case we want a JSON response. This is done by using the Accept header and setting its value to application/json ( -H "Accept: application/json").

All Sell APIs require the following HTTP request headers.

HTTP Header Description
Accept Indicates the response format.
Authorization Defines the authentication method to use.
User-Agent Identifies the agent to the server. You can use the default user agent supplied by curl or specify a custom one.

Example: Retrieve your authenticating user

If the call is successful, the Sell API will return JSON-formatted information about your authenticating user.

curl -v -X GET https://api.getbase.com/v2/users/self \-H "Accept: application/json" \-H "Authorization: Bearer $ACCESS_TOKEN"

Sample Response

Content-Type: application/json; charset=utf-8Content-Language: en
{  "data": {      "id": 1,      "name": "Mark Johnson",      "email": "[email protected]",      "status": "active",      "role": "admin",      "confirmed": true,      "created_at": "2014-08-27T16:32:56Z",      "updated_at": "2014-08-27T17:32:56Z"  },  "meta": {      "type": "user"  }}