API Keys

Create a key, scope it, and store it — in four steps.

Create the key

Go to Dashboard → API Keys → Create key. Give it a name describing where it runs — production-backend, staging-worker — so you know what breaks if you revoke it later.

Grant only the permissions it needs

Pick one or both. A read-only integration should never hold emails:send.

Permission	Grants
emails:send	Send email via POST /v1/emails/send.
emails:read	Read email status, events, and attachment metadata.

Copy it now — it is shown once

Keys start with cmd_. The full value appears exactly once, at creation. After that only a masked preview (cmd_ab12…) is stored and displayed — if you lose it, create a new key rather than hunting for the old one.

Store it in your environment

Never commit a key to source control. Put it in an environment variable and read it at runtime.

.env

CMDSEND_API_KEY=cmd_your_api_key

import { Cmdsend } from 'cmdsend';

const cmdsend = new Cmdsend(process.env.CMDSEND_API_KEY);

Use a separate key per environment, so revoking staging never touches production.

Rotating a key without downtime

Deleting a key takes effect immediately — the very next request using it fails auth. There is no grace period and no soft-disable, so always roll the replacement out first:

Create a second key with the same permissions.
Deploy it to your app and confirm traffic is flowing on the new key.
Delete the old key.

If a key leaks

Delete it immediately — that is the revocation. Then create a replacement and redeploy. Check Analytics & Logs for sends you do not recognise while the key was live.

Using the key in requests is covered in Authentication. Full request/response shapes are in the API Keys reference.