API keys & modes · Vindex docs

Every call to /v1 carries an API key as a bearer token. There are two kinds. Both run the same checks against the same policies; what differs is what happens next.

Shell

curl https://api.getvindex.com/v1/tenant -H "Authorization: Bearer $VINDEX_KEY"

Live and test

	`vx_live_…`	`vx_test_…`
Decisions	`mode: "live"`	`mode: "test"`
Review items	Opened	Opened, marked test
Webhooks	Sent	Never sent
Usage	Counted as live	Counted separately, as test
Reads decisions, review items, usage	Live ones only	Test ones only
Create keys	Test keys (live keys are made in the dashboard)	Test keys only
Revoke keys	Live and test	Test keys only
Rename the workspace	Yes	No
Switch shadow mode	No: in the dashboard	No

Test and live data are apart: a key never reads the other mode's decisions. Asking for them with mode gets 403 mode_forbidden, and the other mode's decision id is a 404.

A test key trying something only a live key can do gets 403 test_key_forbidden:

403 test_key_forbidden

{
  "type": "https://api.getvindex.com/problems/test_key_forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "A test-mode key can't change the tenant.",
  "code": "test_key_forbidden"
}

Use test keys for development, CI and trying things out, and a live key in production. The playground on this site accepts test keys only.

Shown once

A key is shown in full once, when it's made. Vindex keeps only a SHA-256 fingerprint and a short prefix, like vx_live_3f2a, to tell keys apart. Lose a key and you make a new one.

Create keys in the dashboard under API keys. A live key is only made there, where the workspace's owners and admins see it (and get an email about it); an API key gets 403 dashboard_only for one. A test key can also be made with another key:

Shell

curl -X POST https://api.getvindex.com/v1/keys \
  -H "Authorization: Bearer $VINDEX_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode": "test", "label": "ci"}'

The response's key is the only time you'll see it. Label a key after where it lives (ci, prod-worker), so you know what breaks when you revoke it.

Keeping keys safe

Put keys in an environment variable or a secret manager, never in source code.
Never send a live key to a browser or a mobile app. Call Vindex from your server.
GET /v1/keys shows each key's prefix and last_used_at (approximate, to within a few minutes), never the key itself.
Every change a key makes (a policy, a key, a revocation) is recorded in the workspace's audit log with the key's id, refused attempts included.

Revoking

Shell

curl -X DELETE "https://api.getvindex.com/v1/keys/$KEY_ID" \
  -H "Authorization: Bearer $VINDEX_KEY"

A revoked key stops working everywhere within about two minutes. A key can't revoke itself (409 cannot_revoke_current_key), so revoke from another one. Revoking an already revoked key succeeds and changes nothing.