API Keys

Create, list, and revoke API keys programmatically.

POST/v1/api-keys

Create a new API key. The full key is only returned once in this response. Store it securely.

Parameters

Parameter	Type	Required	Description
name	string	Yes	A friendly name for this key (e.g. Production, CI/CD)
scopes	string[]	No	Array of scopes: email:send, email:read, domain:read, domain:write, contact:read, contact:write, form:read, form:write, webhook:read, webhook:write, logs:read, inbound:read, inbound:delete, apikey:manage. Omit it and the key gets the first ten, which is everything except logs:read, inbound:read, inbound:delete and apikey:manage. Name the scopes you need rather than relying on that: a key that can only do its job is a smaller problem if it leaks.

Request Body

json

{
  "name": "Production",
  "scopes": ["email:send", "email:read"]
}

Response

json

{
  "id": "key_abc123",
  "name": "Production",
  "key": "sf_live_abc123def456ghi789...",
  "prefix": "sf_live_a",
  "scopes": ["email:send", "email:read"],
  "created_at": "2026-04-05T12:00:00Z"
}

GET/v1/api-keys

List all API keys on your account. Keys are returned with only the prefix visible for security.

Response

json

{
  "data": [
    {
      "id": "key_abc123",
      "name": "Production",
      "prefix": "sf_live_a",
      "scopes": ["email:send", "email:read"],
      "created_at": "2026-04-05T12:00:00Z",
      "last_used_at": "2026-04-07T08:30:00Z"
    },
    {
      "id": "key_def456",
      "name": "Staging",
      "prefix": "sf_test_b",
      "scopes": ["email:send", "email:read", "domain:read"],
      "created_at": "2026-04-03T09:00:00Z",
      "last_used_at": null
    }
  ]
}

DELETE/v1/api-keys/:id

Revoke an API key. This is immediate and irreversible. Any requests using this key will start returning 401.

Parameters

Parameter	Type	Required	Description
id	string	Yes	The key ID to revoke

Response

json

{
  "id": "key_abc123",
  "deleted": true
}

Key Format and Security

Key Prefixes

Production keys start with sf_live_ and test keys start with sf_test_. This makes it easy to identify keys in your code and logs.

Security Best Practices

Never commit API keys to version control
Use environment variables to store keys
Create separate keys for different environments
Use the minimum required scopes for each key
Rotate keys regularly and revoke unused ones

Hashing

Keys are hashed with SHA-256 before storage. SMTPfast never stores the plain-text key after creation. Only the first few characters (the prefix) are stored for identification.