Verinode Developer

Authentication

Bearer API keys, scopes, and test mode.

Every request carries a bearer key:

Authorization: Bearer vn_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Keys are minted in the dashboard under Settings › Developer, not through the API, and the secret is shown exactly once. Minting requires the admin role on the operator account — the Developer pane isn't shown to other members, so there's no way to bootstrap the first key programmatically.

#Live vs test keys

`vn_live_…`	Acts on your real data. Requires a paid membership; without one, every call returns `403 api_not_entitled`.
`vn_test_…`	Acts as a separate sandbox operator. Free on any plan, never charges Intelligence Units, never touches live data or the intelligence layer.

#The sandbox is empty, not a copy

A test key resolves to its own operator: a blank tenant, not a snapshot of your account. It starts with no jobs, no vendors, and no clients, so GET /v1/jobs on a fresh test key correctly returns { "data": [] }. Write into it to give yourself fixtures.

The isolation runs both ways: sandbox data never appears in your real dashboard, never reaches the intelligence layer, and never affects your benchmarks. GET /v1/api-keys follows the same boundary — a test key lists the sandbox's keys, not your live ones.

Test-key document extraction runs the real (and real-cost) pipeline, so it's capped at 25 documents per day; over that returns 429 sandbox_quota. Everything else on a test key is bounded only by the normal rate limits.

#Scopes

Each key carries scopes; an endpoint declares the scope it needs, and a key missing it gets 403 insufficient_scope. Scopes are chosen at mint time and can't be edited afterwards — to change them, mint a new key. Grant only what the integration calls.

read	List and read your jobs, vendors, and clients; request and download exports.
ingest	Push documents in for extraction, and poll their ingestions.
write	Create records (jobs, clients) and import events.
webhooks	Register endpoints to receive events, and poll outbound events.
keys	List your keys programmatically. Minting still requires the dashboard.

GET /v1/ping needs no scope — any valid key can call it, which makes it the right first call when debugging a 403.