Skip to main content

Veryfi API Keys

Full Access and Scoped API Keys

What Are Veryfi API Keys?

To call the Veryfi API programmatically, every request must carry authentication credentials. These credentials tell Veryfi who you are (CLIENT-ID), that you are authorized (AUTHORIZATION), and optionally that the request has not been tampered with (signature via CLIENT_SECRET).

You manage credentials in one place in the portal:

Where to find keys

app.veryfi.com > Settings > Keys (API Auth Credentials)

Who can see keys

Admin users with API Keys access (non-admins are restricted by default)

Full auth reference

docs.veryfi.com/api/getting-started/authentication

Veryfi now supports more than one kind of API key:

  • Standard API keys (classic): Authorization: apikey USERNAME:API_KEY

  • Bearer – Full Access keys (new): Authorization: Bearer YOUR_API_KEY

  • Bearer – Scoped API keys (new): same Bearer header, limited to chosen permissions

☝️ Bearer Full Access and Scoped Keys are in Beta; please request early feature access by contacting support@veryfi.com

When feature goes live and see full roll out, every new API-type account is created with a Standard API key and an option to add Bearer – Full Access keys or Scoped API keys.

Where to Find Your Keys

  1. Log in to the Veryfi API Portal
    Go to app.veryfi.com and sign in

  2. Open Settings > Keys (API Auth Credentials)
    In the left sidebar, click Settings, then Keys / API Auth Credentials.
    Direct URL: app.veryfi.com/api/settings/keys

  3. Copy the credentials you need
    You will see CLIENT_ID, and key tabs for Standard and Bearer keys. Copy values and store them securely. Treat them like passwords.

Admin access required: only Admin-level team members with API Keys access can view or manage API keys. If you cannot see the Keys page, contact your workspace Admin. Learn more

Key Types: Standard and Bearer

Name in the Hub

Also called

What it is

How you send it

Standard API Keys

Classic / legacy keys

Original keys. Full access only. Still supported.

Authorization: apikey USERNAME:API_KEY

Bearer – Full Access Keys

Full Access keys

Account-level key with full access to everything your account can do

Authorization: Bearer YOUR_API_KEY

Bearer – Scoped API Keys

Scoped keys

Account-level key limited to the actions or presets you choose

Authorization: Bearer YOUR_API_KEY

Two formats, three Hub tabs:

  1. Standard uses apikey USERNAME:API_KEY.

  2. Bearer uses Bearer YOUR_API_KEY, as either Full Access or Scoped.

Every request also needs your account CLIENT-ID, regardless of key type.

Why Bearer and Scoped keys?

Standard keys are all-or-nothing and historically tied to a person(super Admin).

Bearer keys improve that model:

  • Keys belong to the account, not one person

  • Scoped keys limit blast radius if a credential leaks

  • Optional expiration dates

  • Rotate without deleting the whole key record

  • Per-key History (who created, edited, rotated, revoked, and when)

  • Optional per-key webhook URL for async results

If a Scoped key is exposed, damage is limited to what that key was allowed to do.

Credentials Explained

CLIENT_ID

Header name

CLIENT-ID

Example shape

vrfKOMO1x*******pdemo

Role

Identifies your account. Sent on every API call.

The CLIENT-ID header tells Veryfi which account is sending the request. It is not secret on its own, but it must always be present alongside the AUTHORIZATION header. CLIENT-ID: vrfKOMO1x111111111NtKRpdemo

USERNAME and API_KEY (Standard keys)

USERNAME

API_KEY

Header

Part of AUTHORIZATION

Part of AUTHORIZATION

Role

Your Veryfi username for Standard auth

Your secret Standard API key

For Standard keys, USERNAME and API_KEY are combined into one Authorization header:AUTHORIZATION: apikey USERNAME:API_KEY

Example:AUTHORIZATION: apikey democompany:b11111111111111111a111111

Bearer API_KEY (Full Access and Scoped)

Header name

AUTHORIZATION

Value format

Bearer followed by a space and the key secret

Role

Authenticates an account-level Full Access or Scoped key

AUTHORIZATION: Bearer YOUR_BEARER_API_KEY

Use the header format that matches the key type. A Bearer key will not work with the apikey USERNAME:API_KEY format, and a Standard key will not work with Bearer.

CLIENT_SECRET (optional signing)

Header name

Used to generate X-Veryfi-Request-Signature

Role

Private signing secret known only to you and Veryfi

When you send a POST request, you encode the payload and a Unix timestamp using CLIENT_SECRET as the HMAC-SHA256 signing key. The resulting base64 signature goes in the X-Veryfi-Request-Signature header. Veryfi computes the same signature and compares them. If they match, the request is valid.

CLIENT_SECRET signing works the same whether you authenticate with Standard or Bearer keys.

Good news: official Veryfi SDKs handle signing automatically when you pass CLIENT_SECRET to the SDK. Learn more

How the signature works

Required headers on signed requests:

X-Veryfi-Request-Signature: <base64 HMAC-SHA256 of payload+timestamp> X-Veryfi-Request-Timestamp: <Unix timestamp in milliseconds>

Flow:

  1. Build the payload string: concatenate timestamp and request body fields into a canonical string.

  2. Sign it: run HMAC-SHA256 using CLIENT_SECRET as the key.

  3. Encode it: Base64-encode the raw bytes.

  4. Send it: put the encoded value in X-Veryfi-Request-Signature. Signatures expire after 30 minutes.

Python example (manual signing):

import base64, calendar, datetime, hashlib, hmac
dt = datetime.datetime.utcnow()
timestamp_ms = calendar.timegm(dt.utctimetuple()) * 1000
client_secret = "YOUR_CLIENT_SECRET"
payload_str = f"timestamp:{timestamp_ms}"
sig = hmac.new(
    bytes(client_secret, "utf-8"),
    msg=bytes(payload_str, "utf-8"),
    digestmod=hashlib.sha256,
).digest()
signature = str(base64.b64encode(sig), "utf-8").strip()

Full samples (JavaScript, Python, Java, Bash): Authentication docs

Putting It All Together

Standard key request

POST https://api.veryfi.com/api/v8/partner/documents/
Headers:
  CLIENT-ID:                    vrfKOMO1*****NtKRpdemo
  AUTHORIZATION:                apikey username:YOUR_STANDARD_API_KEY
  X-Veryfi-Request-Timestamp:   1710000000000
  X-Veryfi-Request-Signature:   <your HMAC-SHA256 base64 signature>
  Content-Type:                 application/json
Body:
  { "file_url": "https://cdn.veryfi.com/receipts/sample.jpg" }

Bearer key request (Full Access or Scoped) 

POST https://api.veryfi.com/api/v8/partner/documents/
Headers:
  CLIENT-ID:                    vrfKOMO1*****NtKRpdemo
  AUTHORIZATION:                Bearer YOUR_BEARER_API_KEY
  X-Veryfi-Request-Timestamp:   1710000000000
  X-Veryfi-Request-Signature:   <your HMAC-SHA256 base64 signature>
  Content-Type:                 application/json
Body:
  { "file_url": "https://cdn.veryfi.com/receipts/sample.jpg" }

All headers at a glance

Header name

Required?

Purpose

CLIENT-ID

Always

Identifies your account

AUTHORIZATION

Always

Standard: apikey USERNAME:API_KEY. Bearer: Bearer YOUR_API_KEY

X-Veryfi-Request-Signature

Optional (recommended on POST)

HMAC-SHA256 signature proving request integrity

X-Veryfi-Request-Timestamp

Optional (with signature)

Unix timestamp in ms; signature expires after 30 min

Content-Type

POST/PUT/GET

application/json for JSON body requests

APIs and URLs

One set of credentials works across all Veryfi APIs enabled on your account.

The same CLIENT_ID and keys you use for Receipts and Invoices also authenticate Checks, W-9s, Bank Statements, and other endpoints (subject to Scoped permissions on Bearer Scoped keys). You do not need separate CLIENT_ID values per document type.

If use cases need isolation (separate teams, clients, or billing buckets), we can provision additional profiles. Each profile gets its own independent credentials.

Bearer Scoped Permissions and Presets

A Standard key and a Bearer – Full Access key can do everything your account can do.

A Bearer – Scoped key can only do the actions you selected when creating or editing it. Permissions are grouped by product area (Documents, Checks, Bank Statements, W-2/W-8/W-9, and other APIs on your account).

You can turn individual actions on or off, or apply a preset:

Preset

What it grants

Read-only documents

Read access across document-type areas (documents, checks, bank statements, tax forms, and more). Good for reporting and read-only integrations.

Lens SDK

Actions the Veryfi Lens SDK needs inside your app. Enable this on the key your Lens integration uses.

If a Scoped key is missing a permission, Veryfi returns 403 Forbidden for that action even when the key itself is valid.

Special permission: manage API keys

Giving a Scoped key permission to create, edit, or revoke other keys is powerful. That key could widen its own access. The Hub shows a warning next to this option. Enable it only for fully trusted automation (for example your own secure rotation service).

Who can see and manage keys

Profile permission (API Keys access)

API Keys are company-sensitive. Access is controlled under Settings > My Team:

  • Only Admin users can be granted API Keys access

  • Non-Admin users cannot view or manage keys

  • Only Admins who already have API Keys access can grant it to another Admin

  • Details: API Keys Access Permission

Also see:

Per-key managers (Bearer keys)

Each Bearer key has a list of managers: Hub users who can view, edit, rotate, and revoke that key.

  • The account owner is always a manager on every key and cannot be removed

  • Other users only see keys where they are managers (and only if they also have API Keys profile access)

  • Any manager can add or remove other managers from the account user list

Key lifecycle (Active, Revoked, Expired)

State

Meaning

Active

Key works. Shown in the main list.

Revoked

A manager turned the key off. Stops immediately and cannot be re-enabled. Moves to archived view. Secret is hidden permanently.

Expired

Past the optional expiration date. Stops automatically. Treated like revoked: archived, secret hidden.

Manager actions:

  • Create – Generate a new key. Copy the secret immediately at creation time.

  • Rotate – Replace the secret. The old value stops working immediately.

  • Edit – Update name, permissions (Scoped), expiration, managers, or per-key webhook URL.

  • Revoke – Permanently disable the key.

  • Show archived – View revoked and expired keys. Secrets are never shown again.

  • History – Per-key audit log of who did what and when.

If you lose a secret value, rotate the key or create a new one. Veryfi does not re-display a lost secret later.

Per-key webhook URLs (Bearer keys)

By default, async processing results use your account-level webhook URL.

On a Bearer key (Full Access or Scoped), you can set an optional Webhook URL under Advanced when creating or editing the key.

When set:

  • Webhooks for requests authenticated with that key go to the key URL (overrides the account webhook for those requests)

  • Requests made with other keys still use their own setting, or the account webhook if none is set

  • Leave the field empty to keep using the account webhook

Requirements:

  • Public HTTPS URL

  • Internal or private addresses (for example localhost) are rejected

  • Veryfi’s own domains are rejected

Use this when different integrations should deliver results to different systems without sharing one webhook endpoint.

Key rotation

Rotating a key invalidates the old secret immediately.

Integrations using the old value stop working until updated.

When to rotate

  • Before going live (production launch)

  • After any suspected credential exposure

  • When a team member with Admin or key-manager access leaves

  • As part of a scheduled security review (for example every 90 days)

Safe rotation steps

  1. Create a new key, or use Rotate on a Bearer key to keep the same record and permissions

  2. Update every app, secret manager, CI variable, and script

  3. Test with the new value (if you created a second key, keep the old one until validation passes)

  4. Revoke or delete the old key (Rotate invalidates the previous secret immediately)

Full walkthrough for classic add/delete flows: API Keys Management

Programmatic management:

Important: if several products share one profile and one set of keys, resetting or revoking those keys affects every API using that profile. Separate Dev or Staging profiles are not affected.

Step-by-step guide to create a Bearer Key

Case 1: Let's say you need to create a Scoped Key for the Manual review Team that only needs to GET / PUT actions for Receipts & Invoices API

  1. Go to Keys section

  2. Switch to the Scoped tab and hit Create Scoped Key

  3. Name your key and choose what it can access.

    1. Choose explicit name

    2. Set dedicated webhook or expiration

    3. Assign Managers from your team

    5. Choose API and actions for this Scoped Key, hit Create

    6. When saved the Key should appear in the list of keys under Bearer- Scoped keys

Do I need to migrate off Standard keys?

No. Standard keys still work.
​

Recommended path when you are ready:

  1. Keep Standard keys running

  2. Create a Bearer Full Access or Scoped key for a new integration (or a non-production test first)

  3. Point one service at the Bearer key and confirm traffic

  4. Expand Scoped permissions only as needed

  5. Retire unused Standard keys on your own schedule

Prefer Scoped Bearer keys for any new integration that does not need full account access.

Security best practices

Never commit keys to source control

Use environment variables or a secrets manager (AWS Secrets Manager, HashiCorp Vault, or .env files excluded via .gitignore).

Prefer Scoped keys

Give each integration only the permissions it needs.

Use CLIENT_SECRET signing

Signing helps prevent replay and tampering in transit.

Restrict Hub access

Only grant Admin + API Keys access (and key manager roles) to people who need them.

Set expiration on temporary keys

Useful for contractors and short-lived projects.

Rotate on a schedule

And immediately after any suspected leak.

Be careful with “manage API keys” scope

Only on fully trusted automation.

Monitor usage

Check Usage Analytics for unexpected spikes. Set up Duplicate Spike Alerts where available.

Troubleshooting

Symptom

What to check

401 Unauthorized

Key revoked, expired, mistyped, or wrong CLIENT-ID. Confirm the key is Active. Match header format to key type (apikey USERNAME:API_KEY vs Bearer YOUR_API_KEY).

403 Forbidden on some calls only

Scoped key is valid but missing that action. Add the permission or preset, or use Full Access if appropriate.

Webhooks go to the wrong URL

Bearer key may have its own Webhook URL under Advanced. Clear it to fall back to the account webhook, or update it.

Account webhook set, but this traffic ignores it

Per-key webhook overrides account webhook for requests made with that key.

Lens SDK cannot connect

Enable the Lens SDK preset on the Bearer Scoped key used by the app.

Key missing from the list

It may be revoked or expired. Turn on Show archived. Secrets are never shown again for archived keys.

Cannot see any keys / Keys section

Missing API Keys profile access, or not a manager on any key. Account owner can add managers; Admin with API Keys access can enable the profile permission.

Lost the secret value

Rotate the key or create a new one. Secrets are only shown at creation (and after rotate).

Possible leak

Rotate immediately or revoke. Review History for recent changes.

Questions? Email support@veryfi.com or chat live at app.veryfi.com.

Related Articles
Did this answer your question?