Authentication

The HeyVisa API authenticates every request with a bearer token. Keys are scoped to a workspace, can be limited to read-only operations, and can be revoked instantly from the dashboard.

Obtaining an API key

Sign in to your HeyVisa dashboard, open Settings → API Keys, and choose Create new key. Keys are shown once at creation time; store them in a secrets manager immediately. If a key is ever lost or exposed, revoke it and create a replacement.

Prefix	Environment	Behaviour
`hv_live_`	Production	Consumes credits, returns real analysis.
`hv_test_`	Sandbox	Free, returns deterministic sample reports.
`hv_admin_`	Admin	Manages keys, members, and billing. Treat as a root credential.

Header format

Pass the key in the Authorization header using the Bearer scheme. Requests over plain HTTP are rejected.

http

GET /v1/reports HTTP/1.1
Host: api.heyvisa.com
Authorization: Bearer hv_live_8c5b9d2e4f1a3c8d7e6b9a1c2d3e4f5g
Accept: application/json

From a shell:

bash

curl https://api.heyvisa.com/v1/reports \
  -H "Authorization: Bearer $HEYVISA_API_KEY"

Security best practices

Never commit keys to source control. Use a secrets manager (AWS Secrets Manager, Doppler, 1Password) or environment variables loaded at runtime.
Use scoped keys. A worker that only reads reports should not have write access. Create a read-only key for it.
Restrict by IP where possible. Server-side keys can be locked to your egress IPs from the dashboard.
Prefer short-lived deploys. Rotate quarterly even when there has been no incident.
Do not embed keys in client code. Browser, mobile, and desktop apps must call your backend, which then calls HeyVisa.

If a key leaks

Revoke it from the dashboard first, then issue a new key, deploy, and audit the access logs from Settings → Audit Log. We surface the last-used timestamp and IP per key.

Key rotation

HeyVisa supports zero-downtime rotation: create the replacement key first, deploy it side-by-side, watch the dashboard until the old key drops to zero traffic, then revoke it.

bash

# 1. Create the new key in the dashboard
#    Settings → API Keys → Create new key
# 2. Deploy the new key alongside the old one
# 3. Verify traffic on the new key in the dashboard
# 4. Revoke the old key once usage is at zero

curl -X DELETE https://api.heyvisa.com/v1/keys/key_01HXYZ... \
  -H "Authorization: Bearer $HEYVISA_ADMIN_KEY"

Errors

Status	Code	Meaning
401	unauthorized	Missing or malformed Authorization header.
401	invalid_key	Key is revoked, expired, or does not exist.
403	forbidden	Key exists but lacks the required scope.
403	ip_not_allowed	Request originates from an unlisted IP.