An API key is a password for your code. Anyone who holds it can create mailboxes and read mail on your plan until you revoke it, so a little discipline pays off. This guide explains what BoltMail already does to protect keys, and the practical habits that keep your side safe.

What BoltMail does for you

Keys are generated from a cryptographically secure random source and shown to you exactly once. BoltMail stores only a one-way hash, so even a database leak would not expose usable keys. Every request must travel over HTTPS, and the key is accepted only in the Authorization header, never in the URL, because URLs end up in server logs, browser history and proxy caches. Each key has its own rate limit, and each key can only see the mailboxes it created itself. A key can never read the mail of another key.

Use one key per project and environment

Create a separate key for each project, and separate keys for development, staging and CI. The reasons are practical. If one leaks, you revoke one key and nothing else breaks. The dashboard shows which key does what, so you can spot unexpected usage. And a laptop key can have tight restrictions that would be too strict for a build server. Name keys after where they live, such as ci-github or laptop-anna.

Restrict where a key may be used

Each key can carry two optional restrictions, both editable in the dashboard:

  • Allowed IP addresses. Enter the addresses your servers call from, separated by commas. Use this for anything with a fixed address, such as a build server or production host.
  • Allowed websites. Lists the website addresses (the browser Origin or Referer) that may use the key. It is meant for keys that must be called from a page you control.

When you set either list, a request must match at least one of them, otherwise it is refused with a 403 even though the key itself is correct. Anyone who gets hold of a key restricted to your server addresses cannot use it from their own machine.

Be aware that a website list is weaker than an IP list, because the Origin header is set by the client. Prefer the IP list for server-side keys.

Keep keys out of code

The most common leak is a key committed to a repository. Public repositories are scanned by bots within minutes. Follow these rules:

  • Read keys from environment variables or a secrets manager, never from a file that is tracked by git.
  • Add .env to .gitignore before you create it.
  • Never put a key in front-end JavaScript, a mobile app or a browser extension. Anything shipped to a user can be extracted. Call BoltMail from your own server instead and give your front end a narrow endpoint of your own.
  • Do not paste keys into tickets, chat or screenshots. If you must share one, create a short-lived key and revoke it afterwards.

Store keys in your CI system properly

In GitHub Actions, GitLab CI or any other pipeline, store the key as an encrypted secret and expose it to the job as an environment variable. Do not echo it in logs. Most systems mask secrets automatically, but a key transformed by your own script, for example base64 encoded, may escape the mask. Limit which branches may use the secret, and never expose it to builds from forks of public repositories.

Rotate keys on a schedule

Rotation means replacing a key before anything goes wrong. A simple routine works well: every few months, create a new key with the same restrictions, deploy it, check the dashboard to confirm that the old key stopped receiving traffic, then revoke the old one. Because you can hold several active keys at once, rotation needs no downtime. Your plan decides how many active keys you may have, so revoke the old key promptly to free the slot.

If a key leaks

  1. Revoke it immediately from the dashboard. A revoked key stops working at once.
  2. Create a replacement and deploy it.
  3. Check the mailboxes list for addresses you do not recognise and delete them.
  4. Look at your usage meter for unexplained spikes, which show how far the key was abused.
  5. Find out how it leaked, and fix that. Revoking without fixing the cause just repeats the incident.

If your own repository exposed it, remember that deleting a commit does not remove it from history or from clones. Treat any key that was ever public as burned.

Defence in depth on your side

Treat everything that arrives in a mailbox as untrusted input. Email bodies can contain hostile HTML, tracking pixels and links to malicious pages. If your tests render the HTML, do it in a sandbox. Extract codes and links with the API fields instead of opening messages in a real browser session that holds your logins. And never follow a link from a received message without checking where it goes.

A quick checklist

  • One key per project and environment, named clearly.
  • IP allow-list on every key that runs from a known address.
  • Keys only in environment variables or a secrets manager.
  • No keys in front-end code, repositories, logs or screenshots.
  • Rotate every few months, and immediately after a team member leaves.
  • Revoke first, investigate second, when anything looks wrong.

Good key hygiene costs minutes and prevents the kind of incident that costs days. Manage your keys any time from the API keys section of your dashboard.