Authentication & API keys
API keys, the header they travel in, what a key can and cannot do, and how the three credentials stay apart.
API keys#
Your server authenticates to https://api.mm2empire.com/partner/v1/… with an API key in the X-Partner-Key header. Keys are created and revoked by an owner seat in the console under Integration → API keys, and by our staff on request. The secret is shown once, at creation; we store only a hash of it.
GET /partner/v1/ping HTTP/1.1
Host: api.mm2empire.com
X-Partner-Key: pk_live_3f9a…- The secret begins with the key id, so a log line or a support thread can name a key without exposing it.
- A company may hold several keys at once, one per environment or service. Rate limits and idempotency are scoped to the company, not the key, so rotating a key mid-retry still replays the first attempt rather than executing it twice.
- Revoking a key is immediate. The key stays in your list for recognition, marked revoked, and the console records whether your integration has ever used it.
When a key is refused#
| Status | Code | Meaning |
|---|---|---|
| 401 | partner_key_invalid | The header is missing, or the key is unknown or revoked. The message is the same in every case, on purpose. |
| 403 | partner_account_inactive | The key is genuine but your company is suspended. Every seat and key is refused until the account is reinstated. |
Both arrive in the standard error envelope. A 401 is never worth retrying; fix the credential.
Three credentials that never mix#
| Credential | Reaches | Does not reach |
|---|---|---|
API key (X-Partner-Key) | The machine rail, /partner/v1/… | The console. A leaked key cannot mint more keys, move your balance or change settings. |
| Seat session (console login) | Everything a person may read and change about your company | The machine rail. A portal token is refused there. |
| Pop-up session token | One customer's pop-up, for one session | Anything else. It is exchanged once and expires. |
The split is what makes a stolen credential survivable: each one can only do the job it exists for.
Seats and roles#
A company has seats, each a person with their own login and authenticator. An owner can move money, change product settings, create and revoke API keys, and set where notifications go. A member can read everything an owner can, including the delivery log, but cannot change anything that costs money or changes the integration.
A new seat is claimed with a setup code we issue, after which the person chooses a password and enrols an authenticator app. Recovery codes are shown once at enrolment.