# API keys

Manage Groundmail API keys from the public API (Bearer auth with a **full**-scope credential) or the dashboard (**API keys**).

Base URL: `https://api.groundmail.dev`

---

## Scopes

Each key has `scopes` (see [Authentication](https://docs.groundmail.dev/authentication#scopes) for the full list). The dashboard offers three presets:

| Preset | Scopes |
|--------|--------|
| Full (default) | `full` |
| Send only | `emails:send` |
| Read only | `emails:read`, `domains:read`, `account:read` |

Or pick any combination. A key without the scope a request needs gets **403** `insufficient_scope`.

### Limit sending to domains

`allowed_domains` restricts which verified domains a key can send from (the domain of `from`). It needs a send scope and cannot be combined with `full`, since a full key could create an unrestricted one. A send from another domain gets **403** `domain_not_allowed`.

### Test keys

`"test": true` creates a test key. Its token starts with `gm_test_`, and it has scopes like any key. Sends with it run every check (validation, templates, suppressions, idempotency, scheduling) and fire webhooks, but nothing is delivered, and they do not count toward plan limits, the ramp-up, stats or billing. Emails and webhook events from it carry `test: true`. See [Testing](https://docs.groundmail.dev/testing).

### Limit a key to one tenant

`"tenant": "cust_8412"` limits the key to one of your [tenants](https://docs.groundmail.dev/tenants) (its `external_id` or `id`). Use it for anything that acts for one customer:

- It sends only as that tenant. It does not need `tenant` on the send; naming a different tenant gets **403** `forbidden`.
- It sees and manages only that tenant's emails, domains and suppressions.
- It can read its own tenant: `GET /tenants/{tenant}`, `/stats` and `/domains`.
- Everything else (webhooks, templates, received email, deliverability, events, API keys, other tenants, account settings) answers **403** `forbidden`.

Its scopes still apply on top. Since a tenant key cannot create keys, `allowed_domains` can be combined with `full` on it. Deleting the tenant revokes its keys. Tenants are on the pay-as-you-go and Dedicated plans; on Free, `tenant` returns **403** `tenants_not_enabled`.

### Limit a key to mailboxes

`"mailbox_ids": ["mbx_…"]` limits the key to those [mailboxes](https://docs.groundmail.dev/mailboxes), up to 100. Use it for a key you give to one agent:

- It works with those mailboxes' mail. Its scopes still apply on top: `mailboxes:read` can only read, `mailboxes:write` can also label and mark mail, and `mailboxes:send` can send and reply.
- It can't create, change, forward or delete mailboxes.
- Everything else in your account answers **403** `forbidden`.

The key needs `mailboxes:read`, `mailboxes:write`, `mailboxes:send` or `full`; the limit holds on a `full` key too. `mailbox_ids` can't be combined with `allowed_domains`. With `tenant`, the mailboxes must be that tenant's. Keys limited this way list their `mailbox_ids`. A mailbox that doesn't exist is **404** `not_found`. If a mailbox is deleted, the key stays limited to the rest and never widens.

### Legacy `scope`

The `scope` field (`full` or `sending`) still works: `sending` means `emails:send` + `emails:read`. Responses keep `scope` for older clients; it reads `sending` for any key narrower than full.

---

### Azure managed identity

Azure workloads can skip keys entirely: register a managed identity under **API keys → Azure managed identity** in the dashboard and call the API with its Microsoft Entra token. An identity has the same access options as a key (Full, Send only, Read only, a domain limit, a tenant) and is listed and revoked on its own, not through these endpoints. See [Authenticate from Azure with managed identity](https://docs.groundmail.dev/authentication/azure-managed-identity).

## List

`GET /api-keys?limit=25&cursor=…`

```json
{
  "data": [
    {
      "id": "…",
      "name": "Default",
      "scope": "full",
      "scopes": ["full"],
      "allowed_domains": [],
      "test": false,
      "prefix": "gm_abcd",
      "created_at": "2026-07-26T00:00:00.000Z",
      "last_used_at": null
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

---

## Create

`POST /api-keys`

```json
{ "name": "Agent", "scopes": ["emails:send"], "allowed_domains": ["yourdomain.com"] }
```

Add `"test": true` for a test key (`gm_test_…`), or `"tenant": "cust_8412"` for a key [limited to one tenant](#limit-a-key-to-one-tenant). Keys limited to a tenant carry `"tenant"` in list and create responses; other keys have no `tenant` field.

Response (token shown once):

```json
{
  "id": "…",
  "name": "Agent",
  "scope": "sending",
  "scopes": ["emails:send"],
  "allowed_domains": ["yourdomain.com"],
  "test": false,
  "prefix": "gm_…",
  "token": "gm_…",
  "created_at": "2026-07-26T00:00:00.000Z"
}
```

---

## Delete

`DELETE /api-keys/{id}` → `{ "ok": true }`

Cannot delete the key authenticating the request.

---

## SDK / CLI

```ts
await client.apiKeys.create({ name: 'CI', scope: 'sending' })
await client.apiKeys.create({ name: 'Tests', scopes: ['emails:send', 'emails:read'], test: true })
await client.apiKeys.create({ name: 'Acme', scopes: ['full'], tenant: 'cust_8412' })
await client.apiKeys.list()
await client.apiKeys.remove(id)
```

```bash
groundmail keys create --name Agent --scopes emails:send --allowed-domains yourdomain.com
groundmail keys create --name Tests --scopes emails:send,emails:read --test
groundmail keys list
groundmail keys delete --id <id>
```
