Authentication

Every request except GET /health and GET /status carries a personal key in the Authorization header.

Bearer keys#

curl -sS "https://api.quavern.net/v1/networks/tbm" \
  -H "Authorization: Bearer qv_p_…"

Keys are issued by myQuavern for the quavsit service. They are shown once at creation, stored as a hash, named for your own bookkeeping, and revocable at any time from my.quavern.com/account/quavsit. The number of active keys is bounded by your plan (2 on Free, 5 on Pay as you go and Starter, 20 on Pro, 50 on Max); creating one beyond the limit answers 409 key_limit_reached on the account API.

Scopes and audience#

A Quavsit key has audience api.quavern.net and the scope transit:read, which covers every read endpoint of this API. The optional scope account:read lets the same key read GET /v1/me on api.quavern.ai (plan, usage summary); it grants nothing extra on api.quavern.net. Scopes are chosen when the key is created and cannot be widened afterwards; create a new key instead.

What is not accepted#

• Browser session tokens from myQuavern, Marl chat or any other Quavern app. They are rejected with 401 invalid_token.
• Keys issued for another service (for example a Marl key with audience api.quavern.ai): 403 insufficient_scope.
• Organisation service tokens: Quavsit has personal plans only in this version.
• Keys of an account whose email is not verified: 403 email_verification_required.

Public endpoints#

GET /v1/health and GET /v1/status need no key and are not metered. Everything else without a valid key answers 401 authentication_required.

Errors you will meet#

Keeping keys safe#

Send keys only over HTTPS and only from code you control (a backend, a script, a CLI). A key found in a public repository or in browser code should be revoked and replaced. Each key reports its own daily usage on the account page, so one key per application makes leaks easier to spot and cheaper to fix.