Authentication

What your application uses. A key belongs to an organization and acts on its behalf — provisioning domains and mailboxes, sending mail, reading delivery events.

Create one in the dashboard under Developer → API Keys. Name it for the system that will use it — billing-sync, not key2 — and give it the narrowest scopes that let it work.

curl 'https://app.mailyte.com/api/v1/domains' \
  -H 'Authorization: Bearer mk_live_YOUR_API_KEY'

A key looks like mk_live_a7f3b2c9d4e18f06…. The first sixteen characters are a public prefix — safe to log, and what identifies the key in your dashboard. The rest is the secret.

The key is shown once. Only a hash is stored, so nobody — including Mailyte's own staff — can read it back to you. If it is lost, create a replacement and delete the old one.

A key names exactly one organization, so there is nothing to disambiguate and no X-Organization-ID header to send.

If you do send one and it names a different organization, the request is refused rather than ignored. Quietly overriding an explicit instruction is how cross-tenant bugs get written.

Every key carries scopes, and every endpoint requires one. A key with events:read can read the delivery log and cannot delete from it.

Scopes are a ceiling on a key, not a second role system — a member's own permissions still apply. They exist so an administrator can issue a credential narrower than their own authority: a reporting script that can read and provably cannot delete.

A request missing a scope returns 403 and names the scope it wanted, so the fix takes seconds. Scopes cannot be edited after creation: create a replacement key and delete the old one.

Every operation page in the reference states its required scope at the top.

A key can carry an expiry. Setting one turns "we should rotate that" into something that happens whether or not anyone remembers.

A key can also be restricted to a set of addresses or CIDR ranges. A request from anywhere else is refused even with the correct key — useful when the calling system has a stable egress address.

An allowlist that is enabled but empty refuses everything. That is deliberate: failing open would make "restrict this key" a checkbox that silently does nothing.

A key acts as the member who created it, bounded by that member's current access. If they leave the organization or their account is deleted, their keys stop working.

This fails closed on purpose — someone who no longer has authority should not still be lending it out. But it means offboarding can break an integration, so check who owns your keys before removing a member, and prefer to re-issue under someone who is staying.

The Mailbox API — everything the webmail does — takes a different credential. A mailbox token acts as one mailbox holder: their mail, their folders, their calendar.

curl -X POST '<mail server>/api/v1/mailbox-auth/login' \
  -H 'Content-Type: application/json' \
  -d '{"email": "ada@yourdomain.com", "password": "her-mailbox-password"}'

An organization key cannot read anyone's mail, however broadly scoped. If it could, one leaked integration credential would expose every employee's correspondence — so the capability does not exist rather than being guarded. To act as a person, you authenticate as that person.

• Environment variable or secret manager. Never in code you commit.
• One key per system, so revoking one never takes down three.
• Narrowest scopes that work. Most integrations need two or three.
• Set an expiry, and rotate on a known date rather than on discovery.
• Suspect a leak? Delete first, apologise second. Deleting stops the key immediately; investigating first leaves it working while you think.

Keys cannot create or revoke other keys — that stays in the dashboard. A leaked key that could mint its own replacement would outlive the revocation of the key that leaked.