API Authentication

Generating a Key/Secret

Before you can authenticate to the PrintOS APIs you must generate a Key/Secret from within a PrintOS account.

Within PrintOS:

  1. Click the application switcher  at the top right and select "Marketplace"
  2. Select the "Application Connectors" tab.
  3. Click the "Add Connector" tile
  4. Under the "Description" field give a descriptive name that you will remember (i.e. "My Application API Key").
  5. From the "Filter by Application" drop-down select the application you wish to generate this Key/Secret for.
  6. From the "Role" drop-down menu select the roll needed for the API you want to use
  7. Click the "Add" button to generate the Key/Secret
  8. Return to the "Application Connectors" tab to view your Key/Secret

CAUTION:  Providing this Key/Secret to a 3rd party will allow control over these APIs to your account.  Only provide this information to trusted parties.

 

A note about Key/Secret roles:

  • Order Creation - Allows for submission of orders, uploading of files, and querying of those orders/files
  • Order Creation and Enquiries - Allows for Order Creation as well as querying of various system information (Product types, SKUs, etc.)
     

Need Access to PrintOS?

Want to get started with the APIs but don't have a PrintOS account? Click the button below and fill out the form to request a development account. To expedite the request, be sure to provide as much information as possible. 

Request Access

 

HTTP Headers

In order to process any requests over the API the external application must provide the following HTTP header fields:

  • x-hp-hmac-authentication - Key:Signature format where Key is the key created through PrintOS and Signature is a generated HMAC Hex String (see below).
  • x-hp-hmac-date - Current timestamp in ISO 8601 format (YYYY-MM-DDThh:mm:ss.sssZ). Note: Timestamp must be in UTC (GMT / Zulu) time as denoted by the trailing 'Z'.
  • x-hp-hmac-algorithm (Optional) - Valid values are “SHA1” and “SHA256”.  If the header is not provided the system will default to SHA1.

The Signature used for the x-hp-hmac-authentication header is a signed message using either the SHA1 or SHA256 algorithm with the PrintOS generated Secret. The format for the message to sign is: method + " " + path + timestamp where:

  • method - HTTP method used to send this message (e.g. POST, PUT, DELETE).  This value must be in ALL CAPS.
  • path - Endpoint this message is being sent to (e.g. "/api/partner/folder").
  • timestamp - A timestamp generated at time of submission.  The timestamp is the same ISO 8601 (24 hour clock) format as the x-hp-hmac-date header.

Example message to sign: “POST /partner/api/folder2016-04-15T12:00:00.000Z”


Below showcases a way to generate the HMAC Headers. Visit our GitHub to checkout the sample code.

C#
private static void CreateHmacHeaders(string method, string path, HttpClient client)
{
    string timeStamp = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ");

    string stringToSign = method + " " + path + timeStamp;
    HMACSHA1 hmac = new HMACSHA1(Encoding.UTF8.GetBytes(secret));
    byte[] bytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(stringToSign));
    string signature = BitConverter.ToString(bytes).Replace("-", string.Empty).ToLower();
    string auth = key + ":" + signature;

    client.DefaultRequestHeaders.Add("x-hp-hmac-authentication", auth);
    client.DefaultRequestHeaders.Add("x-hp-hmac-date", timeStamp);
    client.DefaultRequestHeaders.Add("x-hp-hmac-algorithm", "SHA1");
}
Java
public String getHmacAuthentication(String method, String path, String timeStamp) throws InvalidKeyException, NoSuchAlgorithmException {
    SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA1");
    Mac mac = Mac.getInstance("HmacSHA1");
    mac.init(secret_key);

    String toHash = method + " " + path + timeStamp;
    byte[] rawHmac = mac.doFinal(toHash.getBytes());
    StringBuilder hash = new StringBuilder();
    for (byte b : rawHmac) {
        hash.append(String.format("%02x", b & 0xff));
    }
        
    return key + ":" + hash.toString();
}
JavaScript
function createHeaders(method, path) {
    var timestamp = (new Date()).toISOString()
    var toSign = method.toUpperCase() + " " + path + timestamp
    var hash = crypto.createHmac("SHA1", secret)
    hash.update(toSign)
    var sig = hash.digest("hex");

    var headers = {
        "X-HP-HMAC-Authentication": key + ":" + sig,
        "X-HP-HMAC-Date":  timestamp,
        "X-HP-HMAC-Algorithm": "SHA1"
    }

    return headers;
}
PHP
function createHmacAuth($method, $path, $timestamp) {
    global $key, $secret;
    $str = $method . ' ' . $path . $timestamp;
    $hash = hash_hmac('sha1', $str, $secret);
    return $key . ':' . $hash;
}
Python
def create_headers(method, path, timestamp):
    string_to_sign = method + ' ' + path + timestamp
    local_secret = secret.encode('utf-8')
    string_to_sign = string_to_sign.encode('utf-8')
    signature = hmac.new(local_secret, string_to_sign, hashlib.sha1).hexdigest()
    auth = key + ':' + signature
    return {
        'content-type': 'application/json',
        'x-hp-hmac-authentication': auth,
        'x-hp-hmac-date': timestamp,
        'x-hp-hmac-algorithm' : 'SHA1'
    }
Ruby
def create_hmac_auth(method, path, timestamp)
    str = method + ' ' + path + timestamp;
    sha1 = OpenSSL::Digest.new('sha1')
    hash = OpenSSL::HMAC.hexdigest(sha1, $secret, str)
    return $key + ":" + hash
end