Authentication & API keys

How access is organized

Your account contains workspaces (the billing boundary — one plan, one bill), and each workspace contains projects (where contacts, campaigns, sending domains, and keys live). Roles are per project: Owners and Admins can create keys there.

One key, two scopes

There is one kind of key (ebk_). When you create it you choose its scope — that's the whole model.

The same key is also your SMTP password — there is no separate SMTP credential to manage, and revoking a key stops both at once. A project key is the easier one to point an SMTP client at, because an all-access key has to say which project it means.

Browser login (CLI & MCP)

The easiest way to get a key is not to copy one at all. In a terminal:

emailbump login

Your browser opens with a pairing code — click Authorize and choose the scope (one project, or all access). The credential lands in ~/.config/emailbump/credentials.json and both the CLI and the MCP server use it automatically. Run emailbump login again any time to switch project or scope, and emailbump logout to remove it. Install the CLI at emailbump.com/cli.

What can this key do?

GET /v1/me (emailbump whoami, or the whoami MCP tool) answers it from the server rather than from what's stored locally: which project the key is in, whether the account's email is confirmed, which sending domains are verified, the from address to use, and whether the compliance footer carries your own postal address or our placeholder. Each of those can refuse a send on its own, which is why it's worth one call before the first one. GET /v1 needs no key at all and lists the API.

No account yet

An account takes an email address and nothing else — no password, no browser.

emailbump signup --email [email protected] --name "Dana" --accept-terms

curl -X POST https://emailbump.com/api/v1/signup \
  -H "Content-Type: application/json" \
  -d '{ "email": "[email protected]", "name": "Dana", "accept_terms": true }'

Either returns two keys and stores the first: a project key for sending, and an account key for creating further workspaces, projects and keys — so nothing in setup needs a browser. Over MCP it's create_account. accept_terms is the person's answer rather than the tool's — creating an account means agreeing to the terms, so ask them first.

There is no password because there needn't be one yet. If they want to sign in to the dashboard later, "Forgot password" sets one on an account that never had one.

Prefer the browser? emailbump signup with no --email opens the authorize page, where "Create an account" sits beside "Log in" — the pairing code survives the detour and the terminal picks up the key. Over MCP that is start_authorization and finish_authorization.

A new account can read the API immediately but can't send until the email address is verified. The verification email carries a link and a six-character code, so nobody has to leave the terminal:

emailbump verify-email --email [email protected] PL8FJD

Create a key in the dashboard

1. 01
   Open API keys

   Go to Developers → API Keys. An administrator or owner can create credentials.

2. 02
   Name the key

   Use a name that identifies the service and environment, such as checkout-production. The name appears next to every request the key makes.

3. 03
   Choose an expiry (optional)

   Leave it as Never, or pick 30 / 90 / 365 days. After that the key stops working.

4. 04
   Store the secret

   Copy the full ebk_ value immediately. Email Bump only shows it once.

Authenticate

Send the key in the HTTP Authorization header using the Bearer scheme — same header for both scopes.

Authorization: Bearer ebk_your_key

Act in a project (all access)

A project-scoped key already knows its project. An all-access key doesn't — with exactly one project it is selected automatically, and with several you name it per call (allowed only where you are an Admin). If you forget, the error lists your projects:

X-Project-Id: <project-uuid>

In the CLI that's --project <uuid> (or EMAILBUMP_PROJECT); MCP tools take an optional project_id. Find project ids with emailbump workspaces:list. Account endpoints — workspaces, projects, domains — need no project, because they say which one in the path.

Set an expiry

An expiring key limits the blast radius of a leak. Set the lifetime when you create the key, in the dashboard or via the API with expires_in_days.

curl -X POST https://emailbump.com/api/teams/{team_id}/api-keys \
  -H "Authorization: Bearer <session>" \
  -H "Content-Type: application/json" \
  -d '{ "name": "ci-runner", "expires_in_days": 90 }'

The key list shows an Expires column and marks a key Expired once the date passes. Rotate or replace it before then to avoid interrupted sends.

Rotate a key

Rotating issues a brand-new secret for the same key in place. The old secret stops working immediately, but the key's name and its request history are preserved — so your activity log stays continuous.

1. 01
   Open the key menu

   On Developers → API Keys, open the ⋯ menu for the key and choose Rotate key.

2. 02
   Copy the new secret

   The replacement ebk_ value is shown once. Update your environment variables or secrets manager.

Request activity

Every API call is logged. On Developers → API Keys you'll find:

• Recent API calls — every request made in this project, with the calling key's name, status, and latency.
• Account API calls — the provisioning calls your all-access keys made: workspaces, projects, and domains.

This lets you see exactly which key did what, and when.

Protect your keys

• Keep keys in server-side environment variables or a secrets manager.
• Use a separate key for each service and environment.
• Never commit keys or include them in browser bundles.
• Prefer an expiry, and rotate a key immediately if it may have been exposed.

Revoke a key

Revocation takes effect immediately. Create and deploy the replacement before revoking an active production key to avoid interrupted sends. Rotating is usually better than revoke-and-recreate because it keeps the key's name and history.