ApiKeys

Create an API key

post/api-keys

Request

  • Base URL: https://api.groundmail.dev
  • URL: https://api.groundmail.dev/api-keys
  • Auth: HTTP bearer

Request body

namestring
scopesApiScope[]

What the key may do, e.g. ["emails:send"] (send only) or ["emails:read", "domains:read", "account:read"] (read only). Takes precedence over scope.

allowed_domainsstring[]

Verified domains the key may send from. Needs emails:send and cannot be combined with full. Sends from other domains get 403 domain_not_allowed.

scope'full' | 'sending'

Legacy. sending means emails:send + emails:read.

testboolean

Create a test key (gm_test_…). It has the same scopes and checks as a live key, but its sends are never delivered: they get simulated events and webhooks and do not count toward plan limits, the sending ramp, stats or billing.

tenantstring

Limit the key to one tenant (its external_id or id). The key sends only as that tenant (naming another gets 403 forbidden), sees and manages only that tenant's emails, domains and suppressions, and can read its own tenant (GET /tenants/{id}, /stats, /domains). Every other endpoint (webhooks, templates, received email, deliverability, events, API keys, other tenants, account settings) answers 403 forbidden. With a tenant, allowed_domains may be combined with full. Deleting the tenant revokes its keys.

Response

API key created (token shown once)

idstring required
namestring required
scope'full' | 'sending' required
scopesApiScope[] required
allowed_domainsstring[] required
testboolean

A test key (gm_test_…).

tenantstring

The tenant this key is limited to (external_id). Present only on tenant keys.

prefixstring required
tokenstring required

Full API key (gm_…, or gm_test_… for a test key), shown once at creation

created_atstring date-time required

Changes

No recorded changes to this operation across all 2 revisions of this API.