API keys
The credentials your servers use, what happens when you rotate one, and how to see what a key has been doing
An API key is how your backend proves it is you. Test keys work against the sandbox; live keys process real applicants. A key belongs to one environment and cannot be used in the other.
This page is for owners and developers. If your team has no engineers, you will probably never open it.
Creating one
Name the key for what it is going to do, confirm with a code from your authenticator app, and the secret is shown once.
Once means once
The secret is displayed a single time, at creation. We do not store a copy we can show you again. Put it straight into wherever your application keeps its secrets. If it is lost, rotate the key and deploy the new one.
In the combined All environments view the dialog makes you choose which environment the key belongs to, because there is nothing to infer it from.
Read and write, or read only
The create dialog also asks what the key is allowed to do. Read and write is the default and is what every key you already have is. Read only creates a key that is refused every write, whatever else it is granted, for the whole life of the key.
Read only says nothing about how much a key can read. That is the next question in the dialog, and the two are independent: a read-only key can be limited to outcomes, and a read and write key can read everything.
Use read only for anything that looks at your data without changing it: a report, an internal dashboard, a nightly export into your own systems, a tool your support team uses to look customers up. Give it to a contractor building an integration and they cannot decide a case or change a setting by accident.
This one cannot be changed later
Read only is fixed for the life of the key. There is no way to widen it afterwards, and that is deliberate: a read-only key you could flip would not be one you could hand out and stop thinking about. If you need it to write, create a new key and revoke the old one.
Read-only keys are marked as such in the list, so you can see at a glance which of your credentials are able to change anything. Read and write keys carry no marker, since that is the ordinary case.
What this key can read
The third question in the create dialog decides how much of a verification the key can see.
Outcomes only is the default and is what every key you already have is. It reads the status, the verdict, the reason codes and the result of each individual check. It cannot read the person: no name, no date of birth, no document number, no images.
Full data adds all of that. The identity we read off the document, including the native-script
spelling and the dates exactly as the card prints them, and the captured images of the document and
the selfie. Your integration asks for it per call, with include=applicant,documents on a
verification, so a key that holds it still returns the plain outcome unless you ask for more.
Choose full data when something of yours needs the person and not just the answer: a customer card in your own support tool, a nightly sync into your systems, a compliance file. Pair it with read only and that thing can see everything and change nothing.
Scopes are fixed at creation
A key cannot gain full data later, and rotating a key keeps the scopes it already had. If a key is
returning 403 when your integration asks for applicant data, it was made as outcomes-only and the
fix is a new key, not a rotation. Create one, swap it in, revoke the old one when nothing is using it.
Keys that carry full data are marked Identity in the list, so you can see at a glance which of your credentials can read a real person.
Keys we issue for you
One thing a key can reach is still never granted by default and cannot be added to a key you make yourself. Ask us and we issue it on your account, where it appears in this list like any other.
Back office marks a key that can open a session acting as one of your own people, which is what connecting your own admin runs on. The key opens the door; what the person on the other side of it can actually do is decided by their seat on the Team page and by nothing about the key. Pair it with read only and their agents can work through your queue without being able to decide anything.
A back-office key needs mapped seats
Each exchange names one person, by the id you use for them, and we resolve it against the
back-office id set on that person's own seat on the Team page. Mapping one colleague does not
authorize a request naming another: every person your admin acts as needs their own mapped seat, and
an unmapped id is refused with NO_SEAT_FOR_EXTERNAL_ID while the key itself authenticates
perfectly. It reads like a broken credential and is not one.
Rotating and revoking
Rotating issues a new secret for the same key. Revoking kills the key immediately, and any integration still using it starts failing on the next call. Neither can be undone, and both ask for your authenticator code first, because a key is production access in a string.
The confirmation for a live key says so in as many words. Read it before you agree to it.
Last used, and what a key has been doing
The list shows when each key was last used, which is the newest API call we have on record for it in the environment you are viewing. A live key's calls are recorded in live, so if the column looks empty, check the environment toggle before you conclude the key is idle.
Select a key and a panel shows its recent traffic. It is drawn from the integration logs, so a role without Logs sees the key but not its history, and the panel says as much rather than showing an empty chart.
If a key made no calls at all, the panel says that too. Every authenticated call your backend signs with it appears within seconds.
Housekeeping worth doing
Give each integration its own key rather than sharing one, so revoking a leaked credential does not take down everything you run. Name keys after the system that holds them. And remember that creating a key subscribes it to nothing: verifications created with a new key reach your endpoints only if a webhook endpoint is set to receive them, which the webhooks page warns you about directly.