Authentication
Every request carries a credential:
Authorization: Bearer emv_...There is nothing else to send. No signature, no timestamp, no second header.
Getting one
Section titled “Getting one”Credentials are issued on request. There is no self-service page yet, and this says so rather than describing one.
Ask us, from the address your account is registered under, and say what the integration is and roughly what volume you expect. You get one credential per integration — see below for why that matters.
Revoking works the same way: tell us which key, by its name or its emv_
prefix, and it stops authenticating immediately.
What is already true of every credential, and will not change when the page arrives:
- It is shown once, at the moment it is created. What the service stores is a digest, so nobody — including us — can recover the token afterwards. A lost credential is replaced, never looked up.
- A key is identified afterwards by a name and its prefix. That is enough to tell two apart and not enough to use one.
- Revocation is immediate and one-way. Nothing stored the original, so reinstating is not a thing that could be offered; a replacement is minted instead.
Why there is no anonymous tier
Section titled “Why there is no anonymous tier”A verifier that answers unauthenticated questions is a directory-harvesting service for whoever finds it, and no rate limit compensates for that. Anonymous access is not a configurable option, and the public checker on emvero.io is not an exception to it — that page runs behind a session and spends the account’s own balance.
What a 401 means
Section titled “What a 401 means”401 means the credential was missing, malformed, unknown or revoked. All four
give the same answer, deliberately: which of them it was is not information the
caller is entitled to, and distinguishing a revoked credential from an invented
one turns the endpoint into an oracle.
A 503 with authentication_unavailable is different in kind — the credential
could not be checked. Nothing was decided about it, and the request should be
retried. See Errors.
Handling the credential
Section titled “Handling the credential”- One credential per integration, not one per company. Revoking is the only way to cut off a compromised integration, and a shared credential means revoking it cuts off everything.
- Server side only. A credential that reaches a browser has been published. This is exactly why the checker on emvero.io is served by a tier that holds the credential rather than by the page itself.
- Revocation is immediate and one-way. A revoked credential is never reinstated — a replacement is minted instead, because nothing stored the original to hand back.
Priority
Section titled “Priority”A credential carries a class that decides who yields when two requests cannot both be served at once: a person waiting on a page outranks a machine holding a connection, which outranks a list being cleaned overnight.
It is a property of the credential and not of the account, so an integration holds a transactional key for its signup flow and a bulk key for its nightly list — bought with the same money at the same rate, the second yielding to the first. It never grants anything: every limit that would refuse a request refuses it either way. See Limits and pacing.