To connect to our API’s, all requests must be authenticated. Please follow the guides below to authenticate against our API’s.

TLS

Connecting to Site Flow RESTful API’s will require at least TLS 1.2 for all HTTPS connections.

If you need help to ensure that your environment is ready for this you can follow one of these checks.

Authentication

Site Flow RESTful API’s use an HTTP Authorization header to pass authorization information. Under the Site Flow authorization scheme, the Authorization header has the following form:

x-oneflow-authorization: Token:Signature

Site Flow User accounts are created via the SiteFlow website and are issued with an access token and secret key. For request authorization, the Token element identifies the access key ID that was used to compute the signature and, indirectly, the user and account making the request.

The Signature element is the HMAC SHA256 of selected elements from the request, and so the Signature part of the Authorization header will vary from request to request. If the request signature calculated by the system matches the Signature included with the request, the requester will have demonstrated possession of the Site Flow secret access key. The request will then be processed under the identity, and with the authority, of the developer to whom the key was issued.

Currently both HMAC SHA256 and HMAC SHA1 are supported. However the more secure HMAC SHA256 is recommended.

In addition to the Authorization header the request must also contain a ‘x-oneflow-date’ header which contains the timestamp used in the Signature encryption, and a ‘x-oneflow-algorithm’ header which contains the hash algorithm that was used (i.e. ‘SHA256’). Below is an example of the headers used in the request

x-oneflow-authorization: 124213431243214:431c0baaac21060fbba3a8c35c74ff565ec0113f6031586b99d978ffb6686e5b

x-oneflow-date: 2022-03-10T17:16:18Z

x-oneflow-algorithm: SHA256

Generating The Authorization Request Header

Below are some code examples which generate the `x-oneflow-authorization` header detailed above. The method in the string to sign is the method used in the RESTful HTTP call, that is, GET/POST/PUT depending on the call being made. The path is the endpoint path, excluding the Site Flow URL. For ex, in a call GET https://pro-api.oneflowcloud.com/api/order, GET would be the method and /api/order the path.

JavaScript

function createHeaders(method, path) {
    // We use the crypto NPM module for encryption of the signature
    var crypto = require('crypto');
    var timestamp = (new Date()).toISOString();
    var toSign = method.toUpperCase() + " " + path + " " + timestamp;
    var hash = crypto.createHmac("SHA256", secret);
    hash.update(toSign);
    var sig = hash.digest("hex");

    var headers = {
        "x-oneflow-authorization": token + ":" + sig,
        "x-oneflow-date":  timestamp,
        "x-oneflow-algorithm": "SHA256"
    }

    return headers;
}

C#.

private static void CreateHmacHeaders(string method, string path, HttpClient client)
{
    // Required for use HMACSHA256:
    using System.Security.Cryptography;

    string timeStamp = DateTime.UtcNow.ToString("yyyy-MM-ddTHH:mm:ssZ");    
    string stringToSign = method + " " + path + " " + timestamp;
    HMACSHA256 hmac = new HMACSHA256(Encoding.UTF8.GetBytes(secret));
    byte[] signatureBytes = hmac.ComputeHash(Encoding.UTF8.GetBytes(stringToSign));
    string signature = BitConverter.ToString(signatureBytes).Replace("-", "").ToLower();
    string authHeader = token + ":" + signature;

    client.DefaultRequestHeaders.Add("x-oneflow-authorization", authHeader);
    client.DefaultRequestHeaders.Add("x-oneflow-date", timeStamp);
    client.DefaultRequestHeaders.Add("x-oneflow-algorithm", "SHA256");
}

PHP

<?php
   $stringToSign = strtoupper($method) . ' ' . $path . ' ' . $timestamp;
   $signature = hash_hmac('sha256', $stringToSign, $secret);
   $authHeader = $token . ':' . $signature;
?>