Authentication

A long-lived secret prefixed vk_. Usage and billing target the workspace that owns the key, not any individual user — the default for production traffic. Read it from VENNA_API_KEY and send it as a bearer token:

curl https://gateway.venna.net/v1/chat/completions \
  -H "Authorization: Bearer $VENNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model": "venna-fast", "messages": [{ "role": "user", "content": "ping" }] }'

When to use it: any unattended, programmatic caller — a backend service, a cron job, a CI step.

A short-lived account token carrying account and workspace context, for interactive apps that already signed a user in. Mint one on the API control plane (not the gateway) with POST /v1/auth/sessions:

curl https://api.venna.net/v1/auth/sessions \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@example.com", "password": "'"$VENNA_PASSWORD"'" }'

Send the returned access-token to the gateway exactly like a vk_ key.

When to use it: a logged-in user is on the other end and billing should follow their plan.

Pay per token from a wallet with no prepaid plan. A request with no valid credential gets a 402 PAYMENT-REQUIRED challenge whose accepts list names the schemes it takes; sign the payload and resend with a PAYMENT-SIGNATURE header carrying the base64 authorization:

curl https://gateway.venna.net/v1/chat/completions \
  -H "PAYMENT-SIGNATURE: $VENNA_PAYMENT_SIGNATURE" \
  -H "Content-Type: application/json" \
  -d '{ "model": "venna-fast", "messages": [{ "role": "user", "content": "ping" }] }'

On Base the gateway accepts upto (authorize-max, settle-actual) and batch-settlement (payment-channel). See the x402 guide for the full challenge → accepts → settlement flow.

When to use it: wallet-based, pay-as-you-go access with on-chain settlement and no sign-up.