Authentication

The API authenticates with a bearer API key:

Authorization: Bearer mvs_<prefix>_<secret>

Minting a key

In the portal, go to Settings → API keys (admin/owner only) and create a key. Choose a name and one or more scopes, then copy the secret — it is shown exactly once and is stored only as a sha256 hash; it can never be retrieved again. If you lose it, revoke the key and create a new one.

A key looks like:

mvs_a1b2c3d4e5f6_0011223344556677889900aabbccddee
     └── prefix ──┘ └────────────── secret ───────────────┘

The prefix is the non-secret lookup index shown in the portal so you can identify the key; the secret is the part you must protect.

Scopes

Scopes are hierarchical — read ⊆ write ⊆ admin:

A request that lacks the endpoint’s required scope returns 403 forbidden.

Revocation & expiry

Keys can be revoked instantly in the portal (the key stops working on the next request — no deletion, so audit references stay intact) and may carry an expiry. A revoked or expired key returns 401 unauthorized.

Security notes

• Send keys only over HTTPS. Never embed them in client-side code or commit them to source control.
• Each key is bound to a single organization; its scope cannot be widened at request time.
• Last-used timestamps are recorded so you can spot stale or leaked keys.