Authentication

API keys, scopes, environments. Read this once and you'll never wonder which token to use.

API keys

Every /v1/* request carries an Authorization: Bearer <key> header. Keys are prefixed vlz_live_… or vlz_test_….

curl https://api.valienz.io/v1/email/messages \
  -H "Authorization: Bearer vlz_live_x1y2z3..."

The secret is shown once at issuance. Lost the secret? Rotate the key — the old one stops accepting requests within 60 seconds.

Scopes

Each key carries a set of scopes (email:send, ai:chat, …). Scopes follow the pattern product:operation; the picker in the dashboard groups them by product.

A request with insufficient scope returns 403 E_SCOPE_INSUFFICIENT. Prefer per-key, per-environment scoping over a single "god" key.

LIVE vs TEST environment

Each key is bound to a single environment. LIVE bills real credits; TEST routes through provider sandboxes (Mailtrap for email, Twilio test creds for SMS, OpenAI sandbox model when available) and is rate-limited but free.

The dashboard topbar pill shows the active env. Switching it changes which keys appear in lookups; production secrets never appear under TEST.

IP allowlist

Optional CIDR allowlist per key. When set, calls outside the allowlist return 403 E_IP_NOT_ALLOWED. CIDR notation: 203.0.113.0/24.

Errors

Code	HTTP	Description	Resolution
E_INVALID_CREDENTIALS	401	API key missing, malformed, or unknown.	Pass a current `vlz_live_…` / `vlz_test_…` key in the Authorization header.
E_API_KEY_REVOKED	401	Key was revoked.	Issue a new key from the dashboard and replace it in your runtime.
E_SCOPE_INSUFFICIENT	403	Key does not carry the required scope.	Issue a new key with the missing scope checked.
E_IP_NOT_ALLOWED	403	Request came from outside the key allowlist.	Add the caller IP/CIDR to the key, or call from an allowed network.