Authentication

Shipwell uses an API authentication process to provide access to the Shipwell APIs. API authentication is typically performed use token-based authentication (or auth).

Each Shipwell environment uses different user tokens and API keys for both the sandbox and production environments (see the list of environments here). Although the API authentication credentials are different per environment, the process for finding your API authentication credentials is the same across environments.

To authenticate to Shipwell's API:

• Find your API authentication credentials, typically a user Token (or in rare cases APIkey )
• Test your key against an API endpoint for the specific environment (e.g. sandbox-api.shipwell.com ) that the key is associated with

Requirements

• A Shipwell user account specifically for API interactions (not your regular user account). Contact your account representative or support@shipwell.com if you don't already have one.
• curl through the command-line, Postman, or a programming language that supports HTTP interactions and JSON ( https://en.wikipedia.org/wiki/JSON ) parsing (i.e. most modern programming languages)

Interactive Code Notebook

Below is an interactive and runnable Google Colab code notebook that allows you to run code and see the results. The python notebook demonstrates how to find and test your API credentials.

• Shipwell Google Colab Notebook for Finding and Testing API Credentials
  • https://colab.research.google.com/drive/1l7PGSOe-LJdgZnkryk0pnEUEfXkjJS8E?usp=sharing

Find your API credentials

With either curl or Postman, perform a HTTP POST to the /v2/auth/token/ endpoint for the environment to access your API authentication credentials, replacing <email> and <password> with your Shipwell API account (a specific user created for API-based interactions) credentials:

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

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);

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)

import java.io.IOException;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

OkHttpClient client = new OkHttpClient();

String basePath = "/v2";
String hostPath = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host_path +
  base_path +
  "/auth/token/"

String requestBody = "{\"email\": \"<email>\",\"password\": \"<password>\"\n}";

Request request = new Request.Builder()
    .url(targetUrl)
    .post(requestBody)
    .header("Content-Type", "application/json")
    .build();

try (Response response = client.newCall(request).execute()) {
    if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
    response.body().string();
}

The API responds with specific information about the user. Find your API authentication credentials in the response (typically user_token):

{
    "token": "<user-token>", // Example: "token": "20d18b9c3deb2b9e544fec888c536fc1". This is the <user-token> value used when making API calls.
    "driver_token": null,
    "driver": null,
    "user": {
       // information about the User, including the User's ID and permissions
    },
    "api_key": "<api-key>" // typically null
}

Test your API credentials

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

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

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);

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)

import java.io.IOException;
import okhttp3.OkHttpClient;
import okhttp3.Request;
import okhttp3.Response;

OkHttpClient client = new OkHttpClient();

String basePath = "/v2";
String hostPath = "sandbox-api.shipwell.com";
String targetUrl = "https://" +
  host_path +
  base_path +
  "/auth/token/me/"

String authToken = "<user-token>";
# Example: authToken = "20d18b9c3deb2b9e544fec888c536fc1";

String authHeaderValue = "Token " + "YOUR_TOKEN_AUTH_VALUE";
// The word "Token" and a space then the authorization token value
// Example: authHeaderValue = "Token 20d18b9c3deb2b9e544fec888c536fc1";

Request request = new Request.Builder()
    .url(targetUrl)
    .get(requestBody)
    .header("Authorization", authHeaderValue)
    .build();

try (Response response = client.newCall(request).execute()) {
    if (!response.isSuccessful()) throw new IOException("Unexpected code " + response);
    response.body().string();
}

The API responds with the currently authenticated user details. Most Shipwell API endpoints utilize the --header 'Authorization: Token <user-token> header to authenticate. If your user token is not authorized for that endpoint then the Shipwell's API responds with a HTTP 401 Unauthorized status code (see list of HTTP status codes):

401: Authorization Required

• All API requests require HTTPS. Calls made over with HTTP will fail.
• API requests without authentication will also fail.

A HTTP 401 Unauthorized response status code means that you do not have permission to make calls against the endpoint or in rare cases, you may need to enter your APIkey instead.

To authenticate with an APIkey use --header 'Authorization: APIkey <api-key> (notice the keyword of Token is replaced with APIkey, but is otherwise similar).

API credentials best practices

• Your API credentials, whether Token -based or APIkey -based 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.