Docs

Home All sections Swagger

Authentication

How to send your API key on every request and what the server does with it.

Last updated June 3, 2026

Every API request needs an Authorization: Bearer <key> header. There is no other auth method.

Using the Python SDK?

The SDK sets this header for you. See Installation and authentication for how to supply the key (constructor argument or VILVIK_API_KEY environment variable).

Sending the key

curl -H "Authorization: Bearer $VILVIK_KEY" \
     https://beta.vilvik.com/api/v1/submissions/?page_size=5

A missing or malformed header returns 401 unauthorized. A header with a key that does not exist, was revoked, or has expired also returns 401.

How the server handles the key

When a request arrives:

  1. The server hashes the key and looks up the hash. We never store the raw secret. If you lose your key, we cannot recover it.
  2. The server checks the key is not revoked, not expired, and that the owning user account is still active and email-verified.
  3. The server checks the key has the scopes required by the endpoint. See Scopes and permissions.
  4. The server records the first use and updates last_used_at and last_used_ip.

Storing your key

  • Treat the key like a password. Anyone with it can act as you.
  • Put it in an environment variable, a secret manager, or your CI's secret store. Do not commit it to git.
  • If you suspect a key was leaked, rotate it from your API keys page. Rotation issues a new secret and invalidates the old one immediately.

A short shell script for testing

export VILVIK_KEY="vlk_live_..."
curl -s -H "Authorization: Bearer $VILVIK_KEY" \
     https://beta.vilvik.com/api/v1/submissions/?page_size=3 \
  | python3 -m json.tool

If you get a 401, double-check the header spelling and that you copied the full key.

Thanks for the feedback!