Guide 6 of 8
API Keys
API keys authenticate SDK and REST API calls. Each key has scopes that restrict what it can do, and an optional inbox restriction that limits which inboxes it can access. The key value is shown only once — store it immediately.
Create an API Key
Via web UI: Settings → API Keys → New API Key → enter a name → select scopes → optionally set an expiry date and inbox restrictions → Create → copy the key.
Via SDK:
const key = await mf.apiKeys.create({
name: 'github-actions-prod',
scopes: ['emails:read', 'inboxes:manage'],
expiresAt: new Date('2025-12-31'),
inboxRestrictions: ['*@qa.acme.mailfork.dev'],
});
console.log(key.key); // shown once — store this immediatelyAvailable Scopes
| Scope | What it allows |
|---|---|
| emails:read | List emails, read email body and attachments, extract OTPs |
| emails:delete | Delete emails and permanently remove them from an inbox |
| inboxes:read | List inboxes and read inbox metadata |
| inboxes:manage | Create, update (pause/resume, catch-all), and delete inboxes |
| folders:manage | Create, rename, and delete folders |
| routing:manage | Create, update, reorder, and delete routing rules |
| api-keys:read | List API keys and read their metadata (not the key value) |
| api-keys:manage | Create, update, and revoke API keys |
Inbox Restrictions
Inbox restrictions are wildcard patterns that limit which inboxes the key can access.
A key with restrictions returns 403 for any inbox outside the matching patterns.
*@qa.acme.mailfork.dev
All inboxes in the qa team under the acme org.
ci@*
Any inbox named ci regardless of team or org.
Rotate a Key
To rotate a key: revoke the old key, then create a new one with the same name and scopes. The old key stops working immediately on revoke — update your secrets manager before revoking in production.
// Revoke the old key
await mf.apiKeys.revoke({ keyId: 'key_abc123' });
// Create a replacement
const newKey = await mf.apiKeys.create({
name: 'github-actions-prod',
scopes: ['emails:read', 'inboxes:manage'],
inboxRestrictions: ['*@qa.acme.mailfork.dev'],
});
console.log(newKey.key); // store this immediately