Skip to main content

Authentication

Credentials​

To access the Veryfi API programmatically, you will need to configure your client with the correct credentials. Make a copy of your CLIENT_ID, Username, and API Key and paste them into their respective Client and Authorization locations.

  1. Go to the Keys section in Settings
  2. Make a copy of your CLIENT_ID
  3. Make a copy of your Username and API Key
  4. Paste them into your Client and Authorization headers

Client Header​

Client Header identifies the partner (ie. you) that is making the requests to Veryfi API.

Required Keys

  • CLIENT_IDREQUIREDString

    Obtained from the Keys section in Settings

Client Header
CLIENT-ID: "CLIENT_ID"

Authorization Header​

The Authorization Header provides credentials that authenticate a user agent with a server, allowing access to protected resources.

Required Keys

  • UsernameREQUIREDString

    Obtained from the Keys section in Settings

  • API_KEYREQUIREDString

    Obtained from the Keys section in Settings


Authorization Header
AUTHORIZATION: 'apikey `USERNAME:API_KEY`'

This is how your authorization header should look:

Authorization Header
AUTHORIZATION: 'apikey api_demo:1f2pdas7jkj389d8sda'
tip

The Interactive API is a convenient way to try API endpoints. Visit the Interactive API v8: Receipts & Invoices test from the portal.

Environment URL​

To be able to make a request to Veryfi, you need a URL that consists of two parts: ENVIROMENT_URL and ENDPOINT_URL. Check the documentation below for the endpoint that best fits your business needs.

Required Keys

  • ENVIROMENT_URLREQUIREDString

    Obtained from the Keys section in Settings

  • API_KEYREQUIREDString

    Check the documentation for Invoices & Receipts, Business Cards, Checks, W-2s, or W-9s for your desired endpoint.


Veryfi Production Environment URL
https://api.veryfi.com/

Signature and Timestamp Headers​

All requests to Veryfi's endpoints should have X-Veryfi-Request-Signature and X-Veryfi-Request-Timestamp headers as an additional layer of authentication. A user encodes a POST request with the CLIENT_SECRET signature. A signed POST request is the request itself and the signature from the request.

Example​

A user sends a POST request to /Documents with a signature to process a new Document.

Veryfi checks the signature sent along with the signature on file. Since the authorized server knows the CLIENT_SECRET, the server can validate and compare if the incoming request's signature coincides with the server's signature.

Required Keys

  • CLIENT_SECRETREQUIREDString

    Obtained from the Keys section in Settings

tip

UTF-8 Encoding​

Every string passed to and from the API needs to be UTF-8 encoded. For maximum compatibility, normalize to Unicode Normalization Form C (NFC) before UTF-8 encoding.

Signatures are valid for 30 minutes from the time of generation.

Signature Header
X-Veryfi-Request-Signature: "Generated Signature"

X-Veryfi-Request-Timestamp value is a Unix Timestamp in milliseconds (ms) since epoch. Since CLIENT_SECRET is essential to the application's password, it automatically does the signing when using a Veryfi SDK.

Timestamp Header
X-Veryfi-Request-Timestamp: "Unix Timestamp"

Refer to the code examples below for a demonstration of how the value of the X-Veryfi-Request-Signature header is generated.

Code Samples​

const crypto = require('crypto')

function customSerialize(value) {
  if (typeof value === 'object' && value !== null) {
    if (Array.isArray(value)) {
      return `[${value.map(customSerialize).join(', ')}]`
    } else {
      let nestedParts = []
      for (const [nestedKey, nestedValue] of Object.entries(value)) {
        nestedParts.push(`${nestedKey}: ${customSerialize(nestedValue)}`)
      }
      return `{${nestedParts.join(', ')}}`
    }
  }
  return JSON.stringify(value)
}

function serializePayload(payload) {
  let parts = []
  for (const [key, value] of Object.entries(payload)) {
    parts.push(`${key}:${customSerialize(value)}`)
  }
  return parts.join(',')
}

function createSignature(secret, payload, timestamp) {
  let payloadStr = `timestamp:${timestamp},${serializePayload(payload)}`
  console.log('Payload string:', payloadStr)

  const hmac = crypto.createHmac('sha256', secret)
  hmac.update(payloadStr)
  return hmac.digest('base64')
}
const dt = new Date()
const utcSeconds = Math.floor(dt.getTime() / 1000)
const timestampMillisecond = utcSeconds * 1000
const requestPayload = {}
const clientSecret = ''

const signature = createSignature(
  clientSecret,
  requestPayload,
  timestampMillisecond
)
console.log(signature)

const headers = {
  'X-VERYFI-REQUEST-TIMESTAMP': timestampMillisecond.toString(),
  'X-VERYFI-REQUEST-SIGNATURE': signature,
  'CLIENT-ID': 'vrfKOMO1xSEM0AWNtKRpdemouT5M1Di8xxudemo',
  AUTHORIZATION: 'apikey api_demo:4b1c01e8ce48ba08832cc299d808demo',
}

console.log(headers)

API Keys Access Permissions​

Verfyi provides additional control for Admin users when granting access to API Keys for safety and security reasons.

Admin users with access to API Keys can only grant API Keys to other Admins. API Keys are not available to non-Admin team members. Visit Managing my team workspace to learn more about managing team members.