How to Obtain an Access Token

Access Tokens

To authenticate yourself to ShipCaddie, you need to include an Access Token in each API call. If you don’t include an Token when making an API request, or if you use an incorrect or expired Token, then ShipCaddie will respond with an error “AccessToken is missing.”

Below is an example for an API request to validate an address. This example shows the Access Token at the start of the body in the request.

 {
   "accessToken": "YTcWPmtxXW6ENMvnbxxp...,
   "addressToValidate": {
     "address1": "2600 Executive Pkwy",
     "address2": "Suite 160",
     "city": "Lehi",
     "countryCode": "US",
     "stateOrProvidence": "UT",
     "postalCode": "84043"
   }
 } 

To obtain an Access Token you’ll need to send a HTTP POST request to https://api.shipcaddie.com/api/v2.1/GetToken either using our API Reference Docs, or through a third party tool such as Postman and Curl.

Endpoints to get an Access Token

There are two different endpoints to get an Access Token:

• accessToken: This endpoint takes a username and password as the credentials. It will return an accessToken and a refreshToken as the response.
  On the ShipCaddie API reference page make a POST call under the “Authentication” header to obtain your access token. Anything you do with your access token is used for production and could incur costs. ShipCaddie recommends that you include the “Test” function for all testing or development purposes.

• refreshToken: When the accessToken expires, you can get another one without the username and password used above. This endpoint takes the refreshToken issued when the original accessToken was given. This will return another valid accessToken and a new refreshToken. NOTE: the refreshToken is a one-time use token. It cannot be used more than once to get a new token. Also, if the accessToken endpoint is called with the same username/password to get a token, it invalidates all previously issued refreshTokens.
  On the ShipCaddie API reference page make a POST call under the “Authentication” header to obtain your refresh token. Use this function for when your access token expires. You will generate a new refresh token every 31 days, so each individual should use their own unique refresh token to avoid an authentication error.

Keep Your Credentials & Access Tokens Safe

Your Credentials and Access tokens give you full access to ShipCaddie’s functionality. With this in mind ShipCaddie recommends that you should treat them as you would treat a password or other sensitive credentials.

Below are some methods that can help keep your Credentials & Access Tokens secure:

• Limit who has access to your credentials and tokens
• Don’t share your credentials
• Create multiple user accounts instead of multiple people having access to a single account. ShipCaddie allows unlimited user accounts for this purpose
• Don’t hard-code your credentials into your source code or config files
• Ensure your Credentials are kept out of any open source sites such as GitHub