Authentication
Send your API key in a header. Here is exactly what that header looks like.
Every request carries your API key in a header. There are two headers you can use — send one, not both.
Authorization: Bearer vrf_live_9f2cA7...X-API-Key: vrf_live_9f2cA7...Notice the difference: Authorization needs the word Bearer in front of
your key. X-API-Key takes the key on its own.
The Authorization header, part by part
Authorization: Bearer vrf_live_9f2cA7...
^^^^^^^^^^^^^ ^^^^^^ ^^^^^^^^^^^^^^^^^^
header name scheme your API key| Part | What to write |
|---|---|
| Header name | Authorization |
| Scheme | The literal word Bearer, then one space |
| Credential | Your key, exactly as issued — it begins vrf_live_ or vrf_test_ |
Bearer is not a placeholder and it is not part of your key. It tells the
server what kind of credential follows, and it is required every time.
A request you can paste
Replace vrf_live_token with your key and run it:
curl --location 'https://api.verifisha.com/api/v1/checks/definitions?page=0&size=2&sortBy=name' \
--header 'Authorization: Bearer vrf_live_token'A 200 with a list of checks means your key works. Anything else — see
what went wrong below.
The same request, if curl is not your thing:
const response = await fetch(
"https://api.verifisha.com/api/v1/checks/definitions?page=0&size=2&sortBy=name",
{ headers: { Authorization: `Bearer ${process.env.VERIFISHA_API_KEY}` } },
);
const page = await response.json();Keep the key in an environment variable rather than in your code. Every example here reads one.
What went wrong
A 401 is almost always the header rather than the key. Every one of these
returns 401:
| What you sent | Fix |
|---|---|
Authorization: vrf_live_... | Add Bearer in front. |
Authorization: Bearer: vrf_live_... | No colon after Bearer — one space. |
Authorization: Bearer <vrf_live_...> | Drop the angle brackets; they mark a placeholder in docs. |
Authorization: Bearer "vrf_live_..." | No quotes around the key. |
X-API-Key: Bearer vrf_live_... | Bearer belongs only to Authorization. Send the bare key. |
| A key pasted with a trailing newline | Trim it — .trim() the value you read from config. |
A vrf_test_ key against live | The environment is part of the key. See environments. |
Still 401 with the header right? The key may be deactivated, or restricted to
endpoints that do not include the one you called. A 403 is different: the key
authenticated, but it lacks the scope that endpoint needs.
Scopes
A key carries scopes. A request whose scope is missing gets 403, not 401.
Each operation in the reference states the scope it needs.
| Scope | Capability |
|---|---|
reports:create | Create and launch reports; add or resend reference requests. |
reports:read | List and read reports, consent state and references. |
monitoring:read | Read recurring checks and alerts. |
monitoring:write | Create recurring checks, and update alerts. |
webhooks:manage | Read and change outbound webhook configuration. |
Dashboard-only actions
Some workspace actions — reviewing, approving and rejecting reports — are available only to people signed in to the Verifisha dashboard. They are not part of this API.
Keeping keys safe
- Use
vrf_test_keys everywhere except production. - Keep keys out of source control, browser code and mobile apps. A key is a password: anything that can read it can spend your balance.
- Rotate by issuing a new key, moving traffic, then deactivating the old one. Deactivation takes effect immediately.