Authentication

Sending Requests to Cove

To authenticate the requests you send to Cove, you'll need to add an HTTP header to every API request. The header should contain your company's API key, which you can either find in the code snippet below if you're currently logged in, or in your API Authentication settings. The header should be formatted as follows:

X-API-KEY: <<apiKey>>
Content-Type: application/json

Optional: Verifying Incoming Requests from Cove

To verify that an incoming request to your Action APIs was indeed generated by Cove, you can do so by checking the request's signature. Every time we send HTTP requests to any of your APIs, we'll sign the request body and provide the signature in a Cove-Signature header. Cove generates these signatures with a private key, and we'll give you a public key to verify the signature's validity. Both the private and public keys are unique to your company.

If you navigated to these docs from your logged in Cove account, your public signing key can be visible here:

<<publicSigningKey>>

If you're not logged in, it will just say PUBLICSIGNINGKEY, so you'll need to go to your API Authentication settings and view it under the "Webhook Signature Verification Key" section.

Validating Requests with the Cove-Signature

To validate an incoming HTTP request, you can do the following:

1. Hash the request body using SHA-256. The input to the hash algorithm is the request's body as raw, binary data.
2. Base64 decode the value in the Cove-Signature header. This will give you the raw binary representation of the signature.
3. Cove's signature was generated with the RSASSA-PKCS1-v1_5 protocol and SHA-256 as the hash, so use your language's standard libraries or crypto packages for verifying the signature accordingly. At a high-level, the process involves decrypting the binary data from step (2) using the public key, and verifying that the decrypted result matches the hash from step (1); however, your language's library will handle many other nitty-gritty details of the RSASSA-PKCS1-v1_5 process.

Javascript Example

// Your public signing key, in PEM format
const pem = `<<publicSigningKey>>`;

// Fetch the part of the PEM key between the header and footer
const pemHeader = "-----BEGIN PRIVATE KEY-----";
const pemFooter = "-----END PRIVATE KEY-----";
const publicKey = pem.substring(
  pemHeader.length,
  pem.length - pemFooter.length
);

// Decode the Base64 string into a buffer
const publicKeyBuffer = Buffer.from(publicKey, 'base64');

const requestBodyBuffer = Buffer.from(req.body, 'utf8');
const signature = Buffer.from(req.headers.get("Cove-Signature"), 'base64');

// Create a CryptoKey object from the public key
const publicKey = await crypto.subtle.importKey(
  'spki',
  publicKeyBuffer,
  { name: 'RSASSA-PKCS1-v1_5', hash: { name: 'SHA-256' } },
  false,
  ['verify']
);

// Verify the signature
try {
  const result = await crypto.subtle.verify(
    { name: 'RSASSA-PKCS1-v1_5' },
    publicKey,
    signature,
    requestBodyBuffer
  );
  if (result) {
    console.log('Signature is valid');
  } else {
    console.log('Signature is invalid');
  }
} catch (error) {
  console.error(error);
}