Message Signature

To generate a message signature, cryptographic keys of the ED25519 variants must first be created.

We currently only support ED25519 key types.

Determine Signature Base

The example signature base below is determined from the content digest example request.

"Authorization": Bearer 123
"Content-Digest": sha-512=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:
"Content-Length": 18
"Content-Type": application/json
"X-Client-Id": 123456
"X-Idempotency-Key": 123456
"@method": POST
"@target-uri": https://api.pipevest.com
"@path": /v1/customers
"@query: ?sort=ASC
"@signature-params": ("Authorization" "Content-Digest" "Content-Length" "Content-Type" "X-Client-Id" "X-Idempotency-Key" "@method" "@target-uri" "@path" "@query");keyid="staging-pipevest-ed25519";created=1732893484;expires=1732893584

Signature Parameters

The field @signature-params contains an ordered list of components that make up the signature base. It is made up of two sections, fields and meta data.

"@signature-params": (fields...);meta

• fields: ordered, space ( ) separated and contained within ellipsis (...)
• meta: unorder, semi-colon (;) separated and specify additional information about the cryptographic operation

The order in which the fields show up in the signature base must match the fields order in the signature params

Generate Message Signature

1. Retrieve Private Key

   Identify the private key for the given environment. You should have one for:

   • Staging
   • Production

   How to Generate Cryptographic keys
2. Determine Signature Base

   Use the instructions here to determine which fields to include to generate the signature.

3. Calculate Signature

   1. Using sha-512, hash the signature base
   2. Sign the resulting hash with the environment specific private key.
   3. Base64 encode the signed hash, this is the final computed message signature (computed-signature).

   For the example request below, the computed-signature will be OTEyMjY4...A5NTNDMEQ=
4. Signature Input

   The signature input is the same as the @signature-params and will be passed along the header. The inputs allow for the signature to be recomputed and verified.

5. Make Signed Request

   Add Signature and Signature-Input to the request header

   • Signature: sig1=:<computed-signature>:
   • Signature-Input: sig1=<@signature-params>

     curl --request POST \
       --url https://api.pipevest.com/v1/customers?sort=ASC \
       --header 'Content-Digest: sha-512=:RK/0qy18MlBSVnWgjwz6lZEWjP/lF5HF9bvEF8FabDg=:' \
       --header 'Content-Length: 18' \
       --header 'Content-Type: application/json' \
       --header 'Authorization: Bearer 123456' \
       --header 'Signature: sig1=:OTEyMjY4...A5NTNDMEQ=:' \
       --header 'Signature-Input: sig1=("Content-Type" "Content-Digest" "Content-Length" "Authorization" "X-Client-Id" "X-Idempotency-Key" "@method" "@target-uri" "@path" "@query");keyid="staging-pipevest-ed25519";created=1732893484;expires=1732893584' \
       --header 'X-Client-Id: 123456' \
       --header 'X-Idempotency-Key: 123456' \
       ...
       --data '{"firstName": "John", "lastName": "Doe"}'
   

Verify Message Signature

1. Retrieve Public Key

   Identify the public key for the given environment. You should have one for:

   • Staging
   • Production

   For webhook message validation, refer to Step 1 in Validate Webhook Message
2. Recompute Message Signature

   1. Use the Signature-Input from the http header to determine the signature base.
   2. Create a sha-512 digest from the signature base

   We will call this computed-message-signature.

3. Identify Header Signature

   You will need to strip the sig1=: prefix and the : suffix to end up with the header-base64-signature.

   In the example below, the header-message-signature equals OTEyMjY4...A5NTNDMEQ=

     curl --request POST \
       --url https://api.pipevest.com/v1/customers \
       --header 'Signature: sig1=:OTEyMjY4...A5NTNDMEQ=:' \
       ....
   

4. Decode Signature

   Using a base64 decoder, decode the header-base64-signature.

   We will call this final result, the header-message-signature.

5. Compare Signatures

   Compare the computed-message-signature to the header-message-signature.

     computed-message-signature === header-message-signature
   

6. Verify or Reject

   Reject the message, if computed-message-signature does not equal header-message-signature.

Example Verification Code:

Javascript

import crypto from 'node:crypto'

// Get the Public key
const publicKey = ...

// Get Signature and Signature inputs from the original http message header
const signature = request.headers['Signature']
const signatureInput = request.headers['Signature-Input']

// Recompute message signature using the signature inputs
const computedSignatureBase = `...` // determined using `signatureInput`
const computedMessageSignature = crypto.createHash('sha512').update(computedSignatureBase).digest()

// Decode the signature to get the signed http message
const headerBase64Signature = signature.match(/:(.*):/).pop()
const headerMessageSignature = Buffer.from(headerBase64Signature, 'base64')

// Use public key to verify that computed and header signatures are the same
const isSignatureVerified = crypto.verify(null, computedMessageSignature, publicKey, headerMessageSignature)

Fields

Fields	Request Types	Required	Note
Content-Type	POST, PUT, PATCH	Yes
Content-Digest	POST, PUT, PATCH	Yes
Content-Length	POST, PUT, PATCH	Yes
Authorization	GET, POST, PUT, PATCH, DELETE	Yes	Not required for /auth
X-Client-Id	GET, POST, PUT, PATCH, DELETE	Yes	Not required for /auth
X-Idempotency-Key	POST, PUT, PATCH, DELETE	Yes
@method	GET, POST, PUT, PATCH, DELETE	Yes
@target-uri	GET, POST, PUT, PATCH, DELETE	Yes
@path	GET, POST, PUT, PATCH, DELETE	Yes
@query	GET, DELETE	Yes
@signature-params	GET, POST, PUT, PATCH, DELETE	Yes

Meta

Name	Description	Required	Note
keyid	This is the id of the public key sent over to pipevest.	Yes	ex: staging-pipevest-ed25519
created	The unix time when the cryptographic operation took place	Yes
expires	Unit time stamp that represents created + 100 ms	No	Not needed, but recommended