Skip to main content

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 needDetail
A Metaventus accountYour company's, or a customer's if you integrate on their behalf
A planDiscovery (free): one API key; Professional and Enterprise: no limit
A secret keyCreated in Admin center → API keys, shown only once
Number of keys per plan

The free Discovery plan includes one API key, enough to connect an integration and try the API. To create more, move to the Professional plan from Billing → Subscription.

Test and production​

A key's prefix says which environment it acts in, and leaves no room for doubt when reading a configuration file:

PrefixEnvironmentWhat it touches
sk_live_…ProductionYour real data, your real sends, your billing
sk_test_…Non-productionA separate environment, with no effect on your real data
pk_live_… / pk_test_…Publishable keyBrowser-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, never 403 — 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.

If a key leaks

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.