Shipwell API

The Shipwell Developer Hub

Welcome to the Shipwell developer hub. You'll find comprehensive guides and documentation to help you start working with Shipwell API as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    API Reference

Authentication

Authenticate users and companies to Shipwell systems

Shipwell APIs use both users tokens and API keys to authenticate. Each Shipwell environment uses different user tokens and API keys 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 [email protected] 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

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

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

{
    "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 APIkey

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

curl --location --request GET 'https://sandbox-api.shipwell.com/v2/auth/me/' \
--header 'Authorization: Token 20d18b9c3deb2b9e544fec888c536fc1'

The API responds with the currently authenticated user. Most 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 401: Authorization Required. A 401 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>.

APIkey 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.

  • If you need to authenticate via bearer auth (e.g., for a cross-origin request), use -H "Authorization: Bearer sw_test_4eC39HqLyjWDarjtT1zdp7dc" instead of -u sw_test_4eC39HqLyjWDarjtT1zdp7dc.

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

  • API requests without authentication will also fail.

Updated 18 days ago

Authentication


Authenticate users and companies to Shipwell systems

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.