API · AUTHENTICATION

Bearer keys, handled honestly.

Every call to /api/v1/* needs an Authorization: Bearer … header carrying one of your keys — the one exception is signed output-download URLs, which carry their own expiring signature instead. Keys are 41 characters, prefixedvvx_live_, and tied to your getvivix account's credit wallet.

Creating a key

Key creation requires a Pro, Pro Plus, or Ultimate plan — Settings hides the "API & Webhooks" section on Free/Standard, and a direct call returns the same 403 TIER_LOCKED either way.

Open Settings → API & Webhooks. Click Create new key, give it an optional name (helpful for distinguishing "production" from "ci" from "local"), copy the plaintext. Accounts can hold up to 10 keys at once — revoke an old one to make room.

The plaintext is shown ONCE. After 30 seconds the panel auto-clears, and there's no way for us to recover it — only the sha256 hash is stored on our side. If you lose it, create a new one and revoke the old.

Using a key

curl https://getvivix.com/api/v1/credits \
  -H "Authorization: Bearer vvx_live_aB3cD4eF5gH6iJ7kL8mN9oP0qR1sT2uV"

That's it. Same header on every request.

Never put a key in client-side code (browser bundles, mobile apps). Anyone who can read your bundle can steal the key and burn your credits. Server-side only — proxy through your own backend if a browser needs to talk to getvivix.

Rotating keys

Best practice: rotate on a schedule, especially after any suspected leak (laptop stolen, contractor offboarded, secrets repo accidentally made public).

  1. Create a new key in Settings.
  2. Update your environment / secrets manager with the new value.
  3. Deploy / restart your service so it picks up the new key.
  4. Revoke the old key. Revocation takes effect immediately — any in-flight requests using the old key still complete; new requests return 401.

Security

  • Keys are stored as sha256 hashes server-side. We literally cannot show you the plaintext after creation.
  • Revocation is soft — we set revoked_at on the row but keep the record for audit. Auth checks reject any key with a non-null revoked_at.
  • Per-tier rate limits + concurrency caps blunt the damage of a leaked key. The worst case is a sleepy weekend before you notice.
  • If you suspect a leak, hit revoke first, ask questions later. New key is one click away.

What not to do

  • Don't share keys across services. One key per service / environment. Easier to revoke, easier to attribute.
  • Don't commit keys to git. Even private repos. Use .env.local, secrets managers, your platform's vault.
  • Don't ship keys to browsers / mobile bundles. Always proxy through a server you control.
  • Don't log full keys. If you need to log them for debugging, log only the prefix (vvx_live_aB3).

Where to next

  • Error codes — including 401 AUTH_MISSING, 401 KEY_INVALID, 401 KEY_REVOKED, and 403 TIER_LOCKED
  • GET /api/v1/credits — first call to make to sanity-check your key
  • Webhooks — the same Settings panel mints a signing secret alongside your keys