Security & Authentication

ShipEngine takes security very seriously, which is why we require all API requests to be made using HTTPS and TLS 1.1 or higher. We also give you the ability to create and revoke API keys quickly and easily via our API dashboard.

Encryption

ShipEngine uses TLS (Transport Layer Security) to encrypt all request and response data. This keeps your sensitive data secure and encrypted - including payment data and customer PII (Personally Identifiable Information) such as addresses and phone numbers.

TLS significantly reduces the risk of data being intercepted or spied upon by third-parties by ensuring the following:

All traffic between your server and ShipEngine is encrypted
Data payloads are checked for integrity to ensure they have not been modified en route
Ownership of the api.shipengine.com domain is verified against ShipEngine's security certificate to ensure you are communicating with the right recipient

ShipEngine requires HTTPS and TLS v1.1 or higher for all API calls. This means that all API calls must be made to https://api.shipengine.com, not http://.

Note

Deprecated security protocols

ShipEngine does not support older security protocols such as TLS 1.0 or any version of SSL. These protocols have been deprecated by the IETF due to security vulnerabilities.

API Keys

To authenticate yourself to ShipEngine, you need to include an API-Key header in each API call. If you don't include a key when making an API request, or if you use an incorrect or expired key, then ShipEngine will respond with a 401 Unauthorized error.

For example, here's an API request to validate an address. Notice the API-Key header in the request.

POST /v1/addresses/validate HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json

[
  {
    "address_line1": "525 S Winchester Blvd",
    "city_locality": "San Jose",
    "state_province": "CA",
    "postal_code": "95128",
    "country_code": "US"
  }
]

curl -iX POST https://api.shipengine.com/v1/addresses/validate \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-H 'Content-Type: application/json' \
-d '[
  {
    "address_line1": "525 S Winchester Blvd",
    "city_locality": "San Jose",
    "state_province": "CA",
    "postal_code": "95128",
    "country_code": "US"
  }
]'

$headers = New-Object "System.Collections.Generic.Dictionary[[String],[String]]"
$headers.Add("Host", "api.shipengine.com")
$headers.Add("API-Key", "__YOUR_API_KEY_HERE__")
$headers.Add("Content-Type", "application/json")

$body = "[`n  {`n    `"address_line1`": `"525 S Winchester Blvd`",`n    `"city_locality`": `"San Jose`",`n    `"state_province`": `"CA`",`n    `"postal_code`": `"95128`",`n    `"country_code`": `"US`"`n  }`n]"

$response = Invoke-RestMethod 'https://api.shipengine.com/v1/addresses/validate' -Method 'POST' -Headers $headers -Body $body
$response | ConvertTo-Json

var myHeaders = new Headers();
myHeaders.append("Host", "api.shipengine.com");
myHeaders.append("API-Key", "__YOUR_API_KEY_HERE__");
myHeaders.append("Content-Type", "application/json");

var raw = JSON.stringify([{"address_line1":"525 S Winchester Blvd","city_locality":"San Jose","state_province":"CA","postal_code":"95128","country_code":"US"}]);

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  body: raw,
  redirect: 'follow'
};

fetch("https://api.shipengine.com/v1/addresses/validate", requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

var request = require('request');
var options = {
  'method': 'POST',
  'url': 'https://api.shipengine.com/v1/addresses/validate',
  'headers': {
    'Host': 'api.shipengine.com',
    'API-Key': '__YOUR_API_KEY_HERE__',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify([{"address_line1":"525 S Winchester Blvd","city_locality":"San Jose","state_province":"CA","postal_code":"95128","country_code":"US"}])

};
request(options, function (error, response) { 
  if (error) throw new Error(error);
  console.log(response.body);
});

<?php

$curl = curl_init();

curl_setopt_array($curl, array(
  CURLOPT_URL => "https://api.shipengine.com/v1/addresses/validate",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 0,
  CURLOPT_FOLLOWLOCATION => true,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS =>"[\n  {\n    \"address_line1\": \"525 S Winchester Blvd\",\n    \"city_locality\": \"San Jose\",\n    \"state_province\": \"CA\",\n    \"postal_code\": \"95128\",\n    \"country_code\": \"US\"\n  }\n]",
  CURLOPT_HTTPHEADER => array(
    "Host: api.shipengine.com",
    "API-Key: __YOUR_API_KEY_HERE__",
    "Content-Type: application/json"
  ),
));

$response = curl_exec($curl);

curl_close($curl);
echo $response;

import requests

url = "https://api.shipengine.com/v1/addresses/validate"

payload = "[\n  {\n    \"address_line1\": \"525 S Winchester Blvd\",\n    \"city_locality\": \"San Jose\",\n    \"state_province\": \"CA\",\n    \"postal_code\": \"95128\",\n    \"country_code\": \"US\"\n  }\n]"
headers = {
  'Host': 'api.shipengine.com',
  'API-Key': '__YOUR_API_KEY_HERE__',
  'Content-Type': 'application/json'
}

response = requests.request("POST", url, headers=headers, data = payload)

print(response.text.encode('utf8'))

require "uri"
require "net/http"

url = URI("https://api.shipengine.com/v1/addresses/validate")

https = Net::HTTP.new(url.host, url.port);
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Host"] = "api.shipengine.com"
request["API-Key"] = "__YOUR_API_KEY_HERE__"
request["Content-Type"] = "application/json"
request.body = "[\n  {\n    \"address_line1\": \"525 S Winchester Blvd\",\n    \"city_locality\": \"San Jose\",\n    \"state_province\": \"CA\",\n    \"postal_code\": \"95128\",\n    \"country_code\": \"US\"\n  }\n]"

response = https.request(request)
puts response.read_body

var client = new RestClient("https://api.shipengine.com/v1/addresses/validate");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
request.AddHeader("Host", "api.shipengine.com");
request.AddHeader("API-Key", "__YOUR_API_KEY_HERE__");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "[\n  {\n    \"address_line1\": \"525 S Winchester Blvd\",\n    \"city_locality\": \"San Jose\",\n    \"state_province\": \"CA\",\n    \"postal_code\": \"95128\",\n    \"country_code\": \"US\"\n  }\n]",  ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

OkHttpClient client = new OkHttpClient().newBuilder()
  .build();
MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "[\n  {\n    \"address_line1\": \"525 S Winchester Blvd\",\n    \"city_locality\": \"San Jose\",\n    \"state_province\": \"CA\",\n    \"postal_code\": \"95128\",\n    \"country_code\": \"US\"\n  }\n]");
Request request = new Request.Builder()
  .url("https://api.shipengine.com/v1/addresses/validate")
  .method("POST", body)
  .addHeader("Host", "api.shipengine.com")
  .addHeader("API-Key", "__YOUR_API_KEY_HERE__")
  .addHeader("Content-Type", "application/json")
  .build();
Response response = client.newCall(request).execute();

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://api.shipengine.com/v1/addresses/validate"
  method := "POST"

  payload := strings.NewReader("[\n  {\n    \"address_line1\": \"525 S Winchester Blvd\",\n    \"city_locality\": \"San Jose\",\n    \"state_province\": \"CA\",\n    \"postal_code\": \"95128\",\n    \"country_code\": \"US\"\n  }\n]")

  client := &http.Client {
  }
  req, err := http.NewRequest(method, url, payload)

  if err != nil {
    fmt.Println(err)
  }
  req.Header.Add("Host", "api.shipengine.com")
  req.Header.Add("API-Key", "__YOUR_API_KEY_HERE__")
  req.Header.Add("Content-Type", "application/json")

  res, err := client.Do(req)
  defer res.Body.Close()
  body, err := ioutil.ReadAll(res.Body)

  fmt.Println(string(body))
}

#import <Foundation/Foundation.h>

dispatch_semaphore_t sema = dispatch_semaphore_create(0);

NSMutableURLRequest *request = [NSMutableURLRequest requestWithURL:[NSURL URLWithString:@"https://api.shipengine.com/v1/addresses/validate"]
  cachePolicy:NSURLRequestUseProtocolCachePolicy
  timeoutInterval:10.0];
NSDictionary *headers = @{
  @"Host": @"api.shipengine.com",
  @"API-Key": @"__YOUR_API_KEY_HERE__",
  @"Content-Type": @"application/json"
};

[request setAllHTTPHeaderFields:headers];
NSData *postData = [[NSData alloc] initWithData:[@"[\n  {\n    \"address_line1\": \"525 S Winchester Blvd\",\n    \"city_locality\": \"San Jose\",\n    \"state_province\": \"CA\",\n    \"postal_code\": \"95128\",\n    \"country_code\": \"US\"\n  }\n]" dataUsingEncoding:NSUTF8StringEncoding]];
[request setHTTPBody:postData];

[request setHTTPMethod:@"POST"];

NSURLSession *session = [NSURLSession sharedSession];
NSURLSessionDataTask *dataTask = [session dataTaskWithRequest:request
completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
  if (error) {
    NSLog(@"%@", error);
  } else {
    NSHTTPURLResponse *httpResponse = (NSHTTPURLResponse *) response;
    NSError *parseError = nil;
    NSDictionary *responseDictionary = [NSJSONSerialization JSONObjectWithData:data options:0 error:&parseError];
    NSLog(@"%@",responseDictionary);
    dispatch_semaphore_signal(sema);
  }
}];
[dataTask resume];
dispatch_semaphore_wait(sema, DISPATCH_TIME_FOREVER);

import Foundation

var semaphore = DispatchSemaphore (value: 0)

let parameters = "[\n  {\n    \"address_line1\": \"525 S Winchester Blvd\",\n    \"city_locality\": \"San Jose\",\n    \"state_province\": \"CA\",\n    \"postal_code\": \"95128\",\n    \"country_code\": \"US\"\n  }\n]"
let postData = parameters.data(using: .utf8)

var request = URLRequest(url: URL(string: "https://api.shipengine.com/v1/addresses/validate")!,timeoutInterval: Double.infinity)
request.addValue("api.shipengine.com", forHTTPHeaderField: "Host")
request.addValue("__YOUR_API_KEY_HERE__", forHTTPHeaderField: "API-Key")
request.addValue("application/json", forHTTPHeaderField: "Content-Type")

request.httpMethod = "POST"
request.httpBody = postData

let task = URLSession.shared.dataTask(with: request) { data, response, error in 
  guard let data = data else {
    print(String(describing: error))
    return
  }
  print(String(data: data, encoding: .utf8)!)
  semaphore.signal()
}

task.resume()
semaphore.wait()

Types of API Keys

You can get your API keys from the ShipEngine dashboard. There are two different types of API keys:

Production API Keys - On the "API Management" page of your ShipEngine dashboard, you'll see your production API keys. Anything you do with a production API key could incur costs, so we don't recommend using these keys for development or testing.
Sandbox API Keys - On the "Sandbox" page of your ShipEngine dashboard, you'll see your sandbox API keys. These are for development and testing purposes. Sandbox keys always start with TEST_ to make it obvious whether a key is production or sandbox. Read more about our sandbox environment for additional details.

Multiple API Keys

You can create any number of either type of key. For example, you may want different keys for different environments, or for different geographical regions, or even separate keys for each server. It's up to you. But regardless of how many keys you have, each type of key has access to all the same data as other keys of that type.

Keep Your Keys Safe

Your API keys give full access to ShipEngine's functionality and therefore should be guarded in the same way you would guard a password or other application credentials.

Limit who has access to your API keys and to the ShipEngine dashboard
Store your keys in a safe place, such as a credential store or key vault
Don't hard-code API keys in your source code or config files
Ensure that your keys are kept out of any version control system, such as GitHub

If your application runs on users' desktops, mobile devices, or web browsers, then your app's network traffic could be visibile to your users - including your API keys. For this reason, we advise that you only call ShipEngine from your server-side code, which runs safely within your network infrastructure.

Warning

Deactivating Keys

If one of your API keys becomes compromised somehow, then you should deactivate it and replace it with a new one as quickly as possible. You can do both of these from the ShipEngine dashboard.

Client-Side Apps & CORS

Many customers develop client-side applications for interacting with the ShipEngine API. For example, you may have a web app or mobile app that your customers use to create shipping labels through ShipEngine. If this is the case, make sure all requests to ShipEngine are sent from your server and not directly from the client application.

The main reason is that you would need to expose your API key to the client. To protect your ShipEngine account from unauthorized access, you should never expose your API key to any client application.

The other reason is that web browsers and mobile apps will not allow a web page to access a resource on an other domain.

For example, if your app runs at https://my-app.com and you try to make a request to the ShipEngine API at https://api.shipengine.com, the browser will generate an error because your domain, my-app.com, is different from the domain to which you are sending the API request, api.shipengine.com. This prevents other web pages you visit from gaining access to the resource - a protection for both your client and the ShipEngine API.

One solution is to host your own API on the same domain as your application. Your client application interacts directly with your API, and your backend server makes requests to ShipEngine. In this manner, your API is a layer between your client application and ShipEngine.

Some APIs may implement CORS (Cross Origin Resource Sharing) to allow web browsers and mobile applications to call the API directly. However, this is not the best practice for keeping private APIs like ShipEngine secure.