API reference / Token auth

API keys

Create scoped API keys (live and test mode), list their metadata, and revoke them. Full secrets are shown exactly once.

GET /v1/api-keys

Token + X-MailStack-Org

List API keys (metadata only — secrets never returned).

Response

[ { "id": "...", "name": "Production", "keyPrefix": "abc12xyz", "maskedKey": "ms_live_abc12xyz_••••", "scopes": ["emails:send"], "isActive": true } ]

POST /v1/api-keys

Token + X-MailStack-Org

Available scopes: emails:send, domains:read, templates:read, templates:write. The returned fullKey is the only time the secret is visible — store it securely.

Request body

{ "name": "Production", "scopes": ["emails:send"], "expiresAt": null }

Response

{
  "key": { "id": "...", "name": "Production", "keyPrefix": "abc12xyz", "scopes": ["emails:send"] },
  "fullKey": "ms_live_abc12xyz_ZmFrZXNlY3JldA"
}

curl https://api.mailstack.voostack.com/v1/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "X-MailStack-Org: org_..." \
  -H "Content-Type: application/json" \
  -d '{ "name": "Production", "scopes": ["emails:send"] }'

DELETE /v1/api-keys/{id}

Token + X-MailStack-Org

Revoke a key immediately (cannot be reactivated).

Response

{ "status": "ok" }

SDKs

Prefer a typed client? The API keys endpoints are covered by the official Node, .NET, Go, and Flutter/Dart SDKs.