Keys and sign-in
The mxgate API key: how to send it, where the CLI stores it, how to recover a lost key and replace a leaked key, and how web sign-in works.
Each account has one API key. This page shows how to use the key, what to do when it is lost or leaked, and how to sign in to the dashboard.
The API key
A key starts with mxg_. Send it with each API call in one of these headers:
Authorization: Bearer mxg_...
x-api-key: mxg_...These calls need no key: POST /v1/signup, the two calls of a key recovery, the two calls of the web sign-in, and the confirmation page of a destination.
The key is shown once: in the answer to the signup. It is also mailed to the account address. mxgate stores only a hash of the key, so it cannot show the key again.
Where the CLI stores the key
mxgate signup saves the key in ~/.config/mxgate/config.json. Only your user can read the file. If XDG_CONFIG_HOME is set, the file is $XDG_CONFIG_HOME/mxgate/config.json.
The environment variable MXGATE_API_KEY has priority over the file. Use it on a server or in CI. mxgate config prints the path of the file and the first characters of the key. The MCP server reads the key from the same places.
A lost key
npx mxgate recover you@gmail.com # mails a token to the account address
npx mxgate recover --token mxr_... # a new key; it is saved in the config file- The token works once, for 60 minutes.
- mxgate sends one recovery mail for an account in 10 minutes.
- When you use the token, you get a new key and the older keys stop working.
- Domains, aliases and SMTP logins do not change.
The first command gives the same answer for an address with no account, so it does not show who has an account. The API calls are:
curl -X POST https://api.mxgate.io/v1/keys/recover \
-H "Content-Type: application/json" -d '{"email":"you@gmail.com"}'
curl -X POST https://api.mxgate.io/v1/keys/recover/confirm \
-H "Content-Type: application/json" -d '{"token":"mxr_..."}'The second call answers 201 with api_key, account and revoked_keys.
A leaked key
npx mxgate key rotateThe command makes a new key and saves it. The key that you had stops working immediately. The API call is POST /v1/keys/rotate with the current key.
The owner of the account gets an email each time the key is replaced this way. If it was not you, run mxgate recover to get the account back. A suspended account can also rotate its key.
If MXGATE_API_KEY is set, it still has the old key after a recovery or a rotation. Change it to the new key.
Signup limits
- One address has one account. A second signup with the same address is
409 already_registered. - Disposable addresses are refused:
422 disposable_email. The key and the confirmation link are mailed to the address, so use an address that you keep. - One IP address can make 3 accounts a day:
429 too_many_signups.
Web sign-in
The dashboard at /login does not use a password. You type the address of the account, and mxgate mails a six-digit code to it. The code works for 10 minutes and for 5 attempts.
The page also has "Continue with Google". Google tells mxgate the email address of your Google account, and nothing else. If that address has an mxgate account, you are signed in. If it has none, mxgate makes the account and mails the API key to that address, as a signup does. An address that Google has not verified is refused.
After the code is correct, the browser holds a session token. A session token starts with mxs_ and works like a key for 30 days. It stays in that browser. "Sign out" ends the session. A key recovery ends all sessions of the account.
The dashboard has the same actions as the CLI: domains with their DNS records, aliases, the message log, notifications, the MCP setup and the plan. Its API key page shows the keys that work now (the first 12 characters, the date and the last use) and makes a new key. The same list is GET /v1/keys.
The API calls behind the page are:
| Call | Body | What it does |
|---|---|---|
POST /v1/login | {"email"} | Mails the six-digit code to the account address. The answer is the same for an address with no account. mxgate sends one code mail for an account in a minute, and at most 5 in an hour. |
POST /v1/login/confirm | {"email","code"} | Answers 201 with session_token, expires_at and account. |
GET /v1/login/google?state= | None | Sends the browser to Google. Google sends it back to the API, and the API sends it to /login with a one-time grant and the same state in the URL fragment. The page accepts the grant only when the state is the one it made. |
POST /v1/login/grant | {"grant"} | Trades the grant for a session. The grant works once, for 2 minutes. |
POST /v1/logout | None | Ends the session of the token that makes the call. |
Send the session token as you send a key: Authorization: Bearer mxs_.... A code that is wrong, used or too old is 400 invalid_login_code. A session that ended is 401 invalid_session. POST /v1/logout with an API key is 400 not_a_session: a key has no sign-out, so use mxgate key rotate to make a key stop working. The API reference has each call in full.
Tokens of connected apps
An app that you connect to the hosted MCP server gets a token that starts with mxo_. It works like a key, with two limits: the app cannot make a new API key, and it cannot connect or remove apps. GET /v1/oauth/apps lists the connected apps; DELETE /v1/oauth/apps/{id} removes one, and its token stops at once. A key recovery removes all of them.