Accounts, environments and keys
Three questions come before the first request: which account, which plan, and which key. This page answers them.
What you need to call the API
| You need | Detail |
|---|---|
| A Metaventus account | Your company's, or a customer's if you integrate on their behalf |
| A professional plan | Creating API keys is not open on the free plan |
| A secret key | Created in Admin center → API keys, shown only once |
On the free plan the API is not open: creating keys requires a professional plan. Change plan from Billing → Subscription, or write to us if your case does not fit the boxes — an integration project is worth a conversation.
Test and production
A key's prefix says which environment it acts in, and leaves no room for doubt when reading a configuration file:
| Prefix | Environment | What it touches |
|---|---|---|
sk_live_… | Production | Your real data, your real sends, your billing |
sk_test_… | Non-production | A separate environment, with no effect on your real data |
pk_live_… / pk_test_… | Publishable key | Browser-side integrations; does not open the endpoints in this reference |
Use one key per environment, and never a production key in a development script: it is the one rule that stops you writing into a company's CRM while trying out pagination.
What a key can see
A key acts within the scope of the account that created it, and of the workspace it is attached to. Two practical consequences:
- a resource belonging to another account answers
404, never403— the answer is deliberately indistinguishable from "does not exist", so as not to confirm that an identifier you do not own is real; - data created through the API carries the key creator's identity as actor, and lands in the key's workspace.
Restricting a key
Three locks, which stack, set at creation or later:
- Scopes: the resources it can reach. A key that only reads contacts has no business in invoices.
- IP addresses: the list of addresses it is accepted from. This is what turns a stolen key into a useless one.
- Expiry date: past it, the key stops authenticating.
Rotating a key without downtime
Create the new key, deploy it, check that it passes, then revoke the old one.
In that order, no request drops. A revoked key answers 401 immediately, and
revocation is final: you do not bring it back, you create another.
Revoke first, investigate afterwards. A key published in a repository, a ticket or a screenshot must be treated as compromised, even with no evidence it was used.