Authentication

Shipwell APIs use both users tokens and API keys to authenticate. Each Shipwell environment uses different user tokens and APIkeys for both the Sandbox and Production environments. Although the keys are different, the process for finding your keys is the same across environments.

To authenticate to Shipwell's API:

Find both your user token and APIkey
Test your key against an API endpoint

Requirements

A Shipwell user account. Contact support@shipwell.com if you don't already have one.
Either Postman or cURL through the command-line.

Find user token and API Key with `auth/token/`

With either curl or Postman, use the auth/token/ endpoint to access your user token and API key, replacing email and password with your Shipwell account credentials:

Trailing slashes

All Shipwell endpoints require a trailing slash / after each new resource.

Request

curljavascriptpython

Copy

Copied

curl --location --request POST 'https://sandbox-api.shipwell.com/v2/auth/token/' \
--header 'Content-Type: application/json' \
--data-raw '{
    "email": "<email>",
    "password": "<password>"
}'

Copy

Copied

const basePath = "/v2";
const host = "sandbox-api.shipwell.com";
const targetUrl = `https://${host}${basePath}/auth/token/`;

const payload = {
    "email": "<email>",
    "password": "<password>"
};

const resp = await fetch(
  targetUrl,
  {
    method: "POST",
    headers: {
      "Content-Type": "application/json"
    },
    body: JSON.stringify(payload)
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host
    + base_path
    + "/auth/token/"
)

headers = {
    "Content-Type": "application/json",
}

json_data = {
    "email": "<email>",
    "password": "<password>",
}

response = requests.post(target_url, headers=headers, json=json_data)
data = response.json()
print(data)

The API responds with specific information about the user. Find your user token on the first line of the response and the API key on the last:

Response

Copy

Copied

{
    "token": "<user-token>",
    "driver_token": null,
    "driver": null,
    "user": {
       // information about the User, including the User's ID and permissions
    },
    "api_key": "<api-key>"
}

Test your token or API Key

With your user token and APIkey, you can verify that your user token works by using the auth/me endpoint, replacing <user-token> with your own:

curljavascriptpython

Copy

Copied

curl --location --request GET 'https://sandbox-api.shipwell.com/v2/auth/me/' \
--header 'Authorization: Token <user-token>'

Copy

Copied

const basePath = "/v2";
const host = "sandbox-api.shipwell.com";
const targetUrl = `https://${host}${basePath}/auth/me/`;

const authToken = "<user-token>";
// Example: const authToken = "20d18b9c3deb2b9e544fec888c536fc1";

const resp = await fetch(
  targetUrl,
  {
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Token ${authToken}`
    }
  }
);

const data = await resp.json();
console.log(data);

Copy

Copied

import requests

base_path = "/v2"
host = "sandbox-api.shipwell.com"
target_url = (
    "https://"
    + host
    + base_path
    + "/auth/me/"
)

auth_token = "<user-token>"
# Example: auth_token = "20d18b9c3deb2b9e544fec888c536fc1"

headers = {
    "Authorization": f"Token ${auth_token}"
}
response = requests.get(target_url, headers=headers)
data = response.json()
print(data)

The API responds with the currently authenticated user. Most Shipwell API endpoints utilize the --header 'Authorization: Token <user-token> header to authenticate. If your user token does not work with that endpoint, Shipwell's API responds with:

Copy

Copied

401: Authorization Required

A 401 HTTP status code means that you do not have permission to make calls against the endpoint, or you might need to enter your APIkey instead.To authenticate with an APIkey use --header 'Authorization: APIkey <api-key>.

API Key best practices

Your API keys can carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.
Authentication to the API uses HTTP Basic Auth. Provide your API key as the basic auth username value. You do not need to provide a password.
All API requests require HTTPS. Calls made over with HTTP will fail.
API requests without authentication will also fail.

Authentication

Requirements

Find user token and API Key with auth/token/

Trailing slashes

Test your token or API Key

API Key best practices

Find user token and API Key with `auth/token/`