Authentication & API keys

Every HTTP API request authenticates with a bearer key:

Authorization: Bearer mw_live_…    # production — accepted only on api.mailway.net
Authorization: Bearer mw_test_…    # sandbox — drives api.mailway.dev

Creating a key

In the console, open the project’s page, go to its Access section (it reads Connect while the project is still being set up) and choose New API key. The team-wide API keys page lists every key for auditing and revoking; creating one needs a project, so it happens on the project’s page. Keys are per-project — the key is the project selection, so there’s no project field in any request. The full key is shown once, when you create it; Mailway stores only a SHA-256 hash, so a key can never be read back — not by you, not by us.

Expiry. The Expires field sets when the key stops working: never (valid until revoked), in 30 days, in 90 days, or in 1 year. Expiry is fixed at creation; to extend it, create a new key and switch to it. An expired key stays listed until you revoke it, and requests with it get 401 key_expired.

What a key looks like

A key is its prefix plus 40 letters and digits: mw_live_ followed by 40 characters for production, mw_test_ followed by 40 characters for the sandbox. Secret scanners can match mw_(live|test)_[A-Za-z0-9]{40}.

Live vs test

The prefix tells you (and Mailway) what a key can do:

	mw_live_…	mw_test_…
Works on	api.mailway.net only	api.mailway.dev
Messages	relay to your providers	stored, never auto-forwarded (sandbox)
Quotas	counted	not counted

The host binding is enforced server-side: a live key presented to the sandbox host, or a test key presented to the live host, is rejected with 401. Pasting the wrong key into the wrong environment fails loudly instead of silently sending.

Handling keys well

• Environment variables, never source control. The usual rule, worth repeating because email keys are a favorite exfiltration target.
• One key per app or environment. Keys are free; revoking one surgically beats rotating a shared one under pressure.
• Revoke from the console the moment a key might have leaked, then create a replacement. Revocation is immediate.
• Keys never work against the console API — and console sessions never work against the HTTP API. A leaked console session cookie can’t send mail, and a leaked send key can’t read your archive.

Note

Sending over SMTP instead? That uses per-project SMTP credentials — a separate, equally-contained credential type.

Errors

Every authentication failure is a 401 with type: authentication_error. Branch on code:

code	Meaning
missing_api_key	No Authorization header, or one that isn’t Bearer mw_live_… / Bearer mw_test_….
invalid_api_key	The key is mistyped, revoked, or belongs to a deleted project.
key_expired	The key’s expiry date has passed.
mode_mismatch	A mw_test_… key on api.mailway.net, or a mw_live_… key on the sandbox host.

Unauthenticated requests are also rate-limited harder (per-IP) than authenticated ones — see Limits.