Skip to content

Authentication

Every request carries a key. One header, no OAuth dance, no token exchange, no expiry to handle.

Not built

Accounts and key issuing do not exist yet. This page describes the design so it can be argued with before it is written. What is already settled: every endpoint requires a key, and none will ever be published without one.

Bearer token

curl
curl https://api.vemon.io/v1/healthcare/prices \
  -H "Authorization: Bearer vm_live_…"

Key format

Keys are issued on signup — a free trial key needs no card, and paid plans issue keys the same way. They are prefixed so they are recognisable in a log or a leaked gist, and so automated secret scanners can match them.

PrefixUse
vm_live_Production. Counts against quota.
vm_test_Returns fixture data. Free, unlimited, never touches real rows.

Handling keys

  • Shown once
    We store a hash, not the key. If you lose it, rotate — we cannot recover it for you.
  • Server-side only
    A key in browser JavaScript is a public key. If you need client-side queries, proxy through your own backend.
  • Rotate without downtime
    Create the new key, deploy it, then revoke the old one. Multiple active keys are fine.
  • Scope per environment
    One key per service per environment, so revoking one thing does not take down everything.

Failure

{
  "error": {
    "type": "unauthorized",
    "message": "API key is missing, malformed, or revoked."
  }
}

A 401 never distinguishes between these cases in the message — doing so would let someone probe which keys exist.