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

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

  • API requests without authentication will also fail.

Copyright © Shipwell 2020. All right reserved.