Authentication
Every request to /api/v1 authenticates with a tenant API key passed in the
X-API-Key header. There are no OAuth flows or bearer tokens on the public API;
the key is the credential.
curl https://api.montavire.com/v1/shipments \
-H "X-API-Key: mv_live_xxxxxxxxxxxxxxxxxxxxxxxx"A missing or invalid key returns 401 Unauthorized as a problem document (see
Errors and rate limits).
Key format and environments
| Prefix | Works on |
|---|---|
mv_live_… | Your real data |
mv_test_… | A separate set of sample data, for building and trying things safely |
A test key works only on your account's sample data: nothing it reads or writes
reaches your live data, it sends no emails, books no carrier labels (labels are
clearly marked samples) and pushes nothing to your sales channels. Webhooks you
register with a test key receive only test events. Test keys come with every
plan; live keys come with Growth and above. An account admin can reset the
sample data from the API keys page. Build with a test key, then create a live
key with the same scopes and swap it in.
Scopes
A key carries one or more scopes of the form <resource>:<action>. A request
is allowed only if the key holds the scope the endpoint requires. Examples:
| Scope | Grants |
|---|---|
supplier:read | Read suppliers (and factories, which share the supplier permission) |
supplier:create | Create suppliers |
supplier:write | Update suppliers and factories |
delivery:read / delivery:create | Read and file deliveries |
label:read | Generate SSCC labels and packing lists |
import:run | Run CSV imports |
event:read | Read the audit event stream |
billing:read | Read subscription status and invoices |
Grant the least a key needs. A call whose key lacks the required scope returns
403 Forbidden, not 404, so you can tell "not allowed" from "not found".
Scopes mirror the in-app permission model. The scope checkboxes shown when you
mint a key are the authoritative, current list for your tenant.
Tenancy and isolation
A key is bound to exactly one tenant. Every read and write is automatically scoped
to that tenant; there is no way to reach another tenant's data with your key. This
is enforced server-side, independent of any filter you pass.
Handling keys safely
- Store keys in a secret manager or environment variable, never in source control.
- Use a distinct key per integration so you can revoke one without breaking others.
- Rotate by minting a new key, deploying it, then revoking the old one.
- Revoke immediately from Developer → API keys if a key leaks.
Updated about 1 hour ago