Run in PostmanStatus PageContact Support
API Reference

Authentication

You'll need a valid API key to use Vizion's API platform.

  • If you need a Vizion API key, contact our sales team.
  • If you are a current customer and don't have an API key, please contact support.

Using an API key

Once you've acquired your API key, all authenticated API requests must contain a header value X-API-Key set with this key.

curl \
    -s '{{baseUrl}}/carriers' \
    -H 'X-API-Key: {{apiKey}}'

Webhook authentication

To ensure data security for our customers, Vizion secures our webhook calls via an HMAC-Based HTTP Signature. Validation of the HMAC-Based HTTP Signature is optional but highly recommended to ensure secure machine-to-machine communication and validate the authenticity of the data you are ingesting.

The Vizion HMAC-Based HTTP Signature includes three main parts:

  1. An expiration indicating the request authentication's time-to-live (TTL)
  2. A HEX encoded digest representing a computed hash of the request body (via the digest header)
  3. An HTTP Signature containing a HEX encoded HMAC signature used to validate the authentication of the request as well as some other metadata

HMAC-Based HTTP signatures

HMAC stands for Hash-based Message Authentication Code. It is a cryptographic authentication technique that uses a hash function and a secret key to build a request signature. HMAC allows systems to verify that a received HTTP request is from a valid, authenticated source and that the data received was not tampered with during transfer.

Verifying a Vizion HMAC signature

Vizion's HMAC Based HTTP Signature implementation was created on the specifications outlined in IETF: Signing HTTP Messages with two exceptions:

  1. We provide the signature in an x-vizion-signature header (NOT the authorization header).
  2. We use HEX encoding instead of BASE64 encoding to simplify signature parsing.

We also provide a digest header, which you will use to validate the request body and the signature. It is encoded in HEX and formatted following the RFC 3230 specification. For example, if a SHA-256 algorithm is used to hash the request body, the header may look like:

SHA-256=857c6c5d5a7ecce4b02c153dd2b86c523ff5dc43bb3be21fdcecf5a972f62bba

The body is converted to a single-line, unformatted JSON string before the computation of the body digest. This is important to note if you want to validate the request body and the signature.

// Valid
{"fieldA":"valueA","fieldB":"valueB","objC":{"fieldC":"valueC"}}
// Invalid
{
    "fieldA": "valueA",
    "fieldB": "valueB",
    "objC": {
        "fieldC": "valueC"
    }
}

A description of our signature parameters is as follows:

FieldDescription
keyIdInformation about the key used to sign the request. For our purposes, this will be hmac-key-[n] where [n] is a number representing which HMAC key of yours we used to sign the request.

For example, when your organization was first created in our system, an HMAC secret was automatically generated. This secret is your first generated HMAC key, so the value would be keyId=hmac-key-1 to indicate your first generated key was used. If, for some reason, the secret is compromised and we had to invalidate the first key and generate a new HMAC secret key, subsequent webhooks would have keyId=hmac-key-2 to indicate that the newly generated secret key was used to generate the signature.
signatureA HEX encoded digital signature you use to validate against your computed signature for request authentication.
algorithmThe hashing algorithm used to construct the signature
createdA Unix Epoch timestamp in milliseconds representing when the signature was created
expiresA Unix Epoch Timestamp in milliseconds representing when the signature expires
headersA space-separated string representing the headers and the order used to sign the request

A valid signature will look something like the following:

Signature keyId=hmac-key-1,signature=e543a61650833ad77c2caaeeda9008b556c6bba41f841edbf5170eaa9439e349,algorithm=SHA-256,created=1685548865944,expires=1685552465944,headers=(request-target) (created) user-agent host date content-type content-length digest

Additional resources

🦉
HMAC Authentication - NodeJS/TypeScript with Express
Open Recipe