# Authentication & API keys

One key, two scopes. Log in from the CLI with a click, or create keys in the dashboard — scoped to one project or your whole account.

## 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.

## No account yet

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

```bash
emailbump signup --email you@company.com --name "Dana" --accept-terms
```

That returns **two** keys and stores the first: a **project key** for sending, and an **account key** for creating further workspaces, projects and keys. Between them nothing in setup needs a browser. Over MCP it's `create_account`. Over HTTP:

```bash
curl -X POST https://emailbump.com/api/v1/signup \
  -H "Content-Type: application/json" \
  -d '{ "email": "you@company.com", "name": "Dana", "accept_terms": true }'
```

`accept_terms` is the person's answer, not the tool's: creating an account means agreeing to the [terms](https://emailbump.com/terms), so ask them first.

There's no password because there doesn't need to 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's `start_authorization` and `finish_authorization`.

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

```bash
emailbump verify-email --email you@company.com PL8FJD
```

Over MCP that's `verify_email_code`. Ask the person to read the code out of their inbox — no tool can or should reach into their mail.

## One key, two scopes

There is one kind of key (`ebk_`). When you create it you choose its scope:

- **One project** — the key is bound to a single project: it sends email, reads and writes that project's contacts, campaigns and lists, and manages that project's [sending domains](https://emailbump.com/docs/domains-api) at `/v1/domains`. Nothing outside the project. This is the key for your application.
- **All access** — the key acts as you across your whole account: it provisions [workspaces](https://emailbump.com/docs/workspaces-api), [projects](https://emailbump.com/docs/projects-api), and [domains](https://emailbump.com/docs/domains-api) through the account API, and can act in any project you admin by naming it per call. For agents and CLIs.

## Browser login (CLI & MCP)

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

```
emailbump login
```

Your browser opens with a pairing code — click **Authorize** and choose the scope (one project, or all access). The credential is stored in `~/.config/emailbump/credentials.json` (0600) 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: https://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.

## Create a key in the dashboard

1. **Open API keys** — Go to **Developers → API Keys**. An administrator or owner can create credentials.
2. **Name the key** — Use a name that identifies the service and environment, such as `checkout-production`.
3. **Choose an expiry (optional)** — or leave it as Never.
4. **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
```

For CI and servers, set it in the `EMAILBUMP_API_KEY` environment variable; the CLI and MCP server read it automatically (env always takes precedence over a stored login).

## Act in a project (all-access keys)

A project-scoped key already knows its project. For an all-access key: with exactly one project it is selected automatically; with several you name it per call (allowed only where its owner is an Admin — and 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.

## Request activity

Every API call is logged. Under **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, and prefer project scope unless you need provisioning.
- Never commit keys or include them in browser bundles.
- Prefer an expiry, and rotate a key immediately if it may have been exposed.

## Rotate and revoke

Rotating issues a new secret in place — the old secret dies immediately, the key's name and request history continue. Revocation kills the key immediately; create and deploy the replacement first to avoid interrupted sends. Both are on **Developers → API Keys** (project keys and all-access keys alike).