Signature Authentication

Generate Public/Private key pair

The following commands will generate a ECDSA (secp256k1) private/public key pair in the directory it is run. openssl must be installed on the machine before running.

NOTE: This step is not needed for verifying webhooks. Instead you will use UTB's public key provided to you.

Shell

openssl ecparam -name secp256k1 -genkey -noout -out utb-private-key.pem 
openssl ec -in utb-private-key.pem -pubout > utb-public-key.pem

The public key must be zipped and sent to your UTB contact to finish setting up you API subscription.

Required Headers

The following headers must be set for every request:

  • Date

  • X-UTB-Subscription-Key

  • X-UTB-Signature-Nonce

  • X-UTB-Signature-Version

  • X-UTB-Signature

Date

Standard HTTP header that must follow HTTP standards for formatting.

Date: Wed, 21 Oct 2015 07:28:00 GMT

X-UTB-Subscription-Key

Either the primary or secondary subscription key. This will be provided by UTB.

X-UTB-Signature-Nonce

The nonce must be a single use generated value. We suggest using UUID/GUID for this field. Each request must use a different nonce.

X-UTB-Signature-Version

Represents the version of signature authentication being used. Valid values: v1

X-UTB-Signature

To calculate the signature of your request:

  1. Concatenate the request body, Date header value, and X-UTB-Signature-Nonce header value.

  2. Digitally sign using your private key and the SHA256withECDSA algorithm

    • Cryptography libraries can usually compute digital signatures, however, to do it manually:

      1. Hash the raw signature with HMAC256

      2. Encrypt the hashed signature with your ECDSA secp256k1 private key