Developer: API keys

What this page is

Developer: API Keys is where an admin mints, scopes, rotates, and revokes the credentials that let an outside system, a script, or an internal integration talk to Verinode's API on the operator's behalf. Every key is scoped to exactly the permissions it needs, live keys only work against real data on a paid membership, and the full secret is displayed exactly once, at the moment it is created or rolled. After that, Verinode stores only a hash of it, never the plaintext again.

This is not a benchmarks or IQ surface. It is plumbing: a way to pull your own jobs, vendors, and clients out of Verinode programmatically, push documents in for extraction, or register a webhook so your own systems hear about events in real time. Nothing here changes what Verinode analyzes or recommends inside the product.

Where to find it

Open Settings and look for the Developer group in the settings index, below Data & Privacy. Inside it, one row:

• API Keys, subtitle "Create, roll, revoke," at /settings/developer.

Two conditions gate this page, and both must be true or you won't see the Developer group at all:

1. Your role is admin. Team members with the user or data_contributor role never see this row, and hitting the URL directly redirects them back to /settings.
2. The Operator API is enabled for your environment. This is a platform-wide feature flag, off by default while the API rolls out. If it isn't on yet, the Developer group is simply absent from your Settings index, the same as if the row didn't exist.

The three panels

The page is one flat column, no cards inside cards: a documentation link, a form for minting a new key, and a list of the keys you already have.

1. Documentation

A single link, "Read the API reference," pointing to docs.verinode.ai/reference. It opens in a new tab and covers the base URL, how authentication works, every endpoint, and webhook payloads. This help article covers the Settings UI for managing keys; the reference site covers what you can actually call once you have one.

2. New Key

The caption under the section title spells out the core rule: "Live keys need a paid membership; test keys run against an isolated sandbox and never touch real data." Three fields, then a button.

• Key Name. A free-text label so you can tell keys apart later (the placeholder example is "Accounting export"). Name it for what it's for, not who made it, since the name is what shows up in the list later.
• Mode. A two-way toggle, Test or Live. Test is selected by default.

- Test keys run against a dedicated sandbox operator account that Verinode provisions automatically the first time you create one. It's tied to your real operator account behind the scenes but holds none of your real data, so you can build and break an integration without any risk to your live jobs, vendors, or clients. - Live keys run against your real operator data. Creating one requires an active paid membership. If your account is still on the free Contributor tier, the form returns "Live API keys require a paid membership (Executive, Premier, or Reserve). Use a test key to evaluate." instead of minting the key.

• Scopes. A checkbox list, one row per capability, each with its own plain-language hint. Read is checked by default; you can add or remove any combination, but at least one has to stay checked or the form returns "Select at least one scope."

| Scope | What it hints | What it actually grants | |---|---|---| | Read | "List your jobs, vendors, and clients." | Pulls your existing records out of Verinode. | | Ingest documents | "Push documents in for extraction." | Sends files into Verinode's extraction pipeline, the same pipeline that reads forwarded emails and uploads. | | Write records | "Create and update records directly." | Creates or edits records straight through the API, bypassing the document-extraction path entirely. | | Manage keys | "List keys programmatically." | Lets a script enumerate the operator's own keys. It does not let a key create or revoke other keys. | | Manage webhooks | "Register endpoints to receive real-time events." | Lets an integration register an endpoint to receive Verinode events as they happen, instead of polling. |

Click Create Key. If the name is blank, the scope list is empty, or a live key is requested without a paid membership, the form shows the error in red under the fields and nothing is created. On success, the new key drops into the list below and a modal pops up showing the raw secret, more on that in a moment.

3. Your Keys

Every key you've created, newest first, laid out as hairline-separated rows (no card frame, the rows just flow). Each row shows:

• Name and a small Test or Live tag next to it.
• Prefix, a partial identifier like vn_live_a1b2c3…. This is the only part of the secret Verinode keeps in plaintext, purely so you can recognize which key is which in a list. The rest of the secret was never stored after creation.
• Scopes, the humanized scope labels from the table above, joined with a middle dot ("Read · Ingest documents"). A key somehow left with no scopes reads "No scopes."
• Last used, a date if the key has made at least one authenticated call, or "Never" if it hasn't been used yet.
• Status, one of three states:

- Active (green): the key works right now. - Rotating (old secret expires soon) (yellow): this is the old half of a key you just rolled. It still authenticates, but only for a short overlap window, then it stops working for good. - Revoked (gray): dead. It no longer authenticates at all.

Only Active rows show action buttons: Roll and Revoke. Once a key has entered Rotating or Revoked, there's nothing left to click on that row; you manage the replacement key instead.

Empty state. With no keys created yet, the panel reads: "No keys yet. Create one above to get started."

Rolling a key

Rolling replaces a key's secret without touching its name, mode, or scopes. Use it when a secret may have leaked, when a scheduled credential rotation is due, or when you just want a clean handoff between two versions of an integration without breaking anything mid-cutover.

1. 1Find the Active key you want to rotate in Your Keys.
2. 2Click Roll.
3. 3Verinode mints a brand-new secret with the same name, mode, and scopes, and shows it once in the "Save Your API Key" modal, exactly like a fresh creation.
4. 4Update whatever system holds the old secret with the new one.
5. 5The old secret keeps working for 24 hours after the roll (shown as Rotating (old secret expires soon) in the list), then it's automatically shut off for good. There's no separate step to finish the rotation, the 24-hour window closes on its own.

Revoking a key

Revoking kills a key immediately, with no grace window. Use it when an integration is retired, a secret leaked and you don't want even a short overlap, or a key was created by mistake.

1. 1Find the Active key in Your Keys.
2. 2Click Revoke.
3. 3The key's status flips to Revoked immediately. Any request using that secret starts failing right away, there is no delay like there is with rolling.

Revoking is permanent. There's no undo and no way to restore the same secret, if you need the integration back, create a new key.

The one-time secret

Whether you just created a key or rolled one, the raw secret appears exactly once, in a modal titled "Save Your API Key." The modal reads: "This is the only time the full key is shown. Copy it now and store it somewhere safe. You can't retrieve it again, but you can roll or revoke it anytime." Below that, the full secret sits in a monospace box you can select manually, plus a Copy Key button that copies it to your clipboard and briefly relabels itself "Copied" to confirm. Click Done once you've saved it somewhere safe (a password manager or your own secrets store, not a chat message or a shared doc).

If you close the modal without copying the secret, it is genuinely gone. Verinode never stores the plaintext, only a one-way hash of it, so there is no "forgot to copy it" recovery path. Roll the key to get a fresh secret instead.

Live versus test, in practice

A live key acts as your real operator account: reads return your actual jobs, vendors, and clients, and a write- or ingest-scoped live key changes or adds real records. A test key acts as an isolated sandbox account Verinode provisions the first time you make one, so you (or a developer building against your account) can exercise the whole API surface, including ingesting documents and writing records, without any of it touching your live business data or membership.

There's no charge difference tied to scopes or key count, the gate is simply that live mode requires an active paid membership. If you're evaluating the API before committing, build against a test key first; nothing you do there reaches your real account.

Data sources

Related

• Settings overview
• Members & roles
• Membership & billing
• Connecting your data
• Forwarding documents