Vertex

Docs

API keys

Keys authenticate every call to Vertex. Treat live keys like passwords: scope them tightly, rotate them on a schedule, and never ship them in client bundles unless they are publishable.

Key types

vx_live_ keys write real data and count against quota. vx_test_ keys write to a scratch environment wiped nightly — use them in CI and staging.

The key embedded in the browser snippet is publishable: it can only submit events, never read data, so exposing it in HTML is safe by design.

Scopes

Every key carries one or more scopes. write:events is the only scope a publishable key can hold. read:reports allows exporting funnels and retention data. admin:keys can mint and revoke other keys — give it to your infrastructure tooling only.

bash
# Create a narrowly-scoped key for a data pipeline
vertex keys create \
  --name etl-export \
  --scope read:reports \
  --expires 90d

Rotate keys

Rotation issues a replacement and starts a grace period on the old key, so deploys can roll gradually. The old key keeps working for 24 hours (configurable up to 7 days), then returns 401.

Rotate immediately if a key ever lands in a log file, a screenshot or a public repository.

bash
curl -X POST https://api.lorem.example/v1/keys/key_lorem42/rotate \
  -H "Authorization: Bearer $VERTEX_ADMIN_KEY" \
  -d '{"graceHours": 24}'

Best practices

One key per deploy target — never share a key between staging and production. Set expiry dates on everything except the publishable snippet key. Audit the key list quarterly and revoke anything you cannot name the owner of.

← Funnels