Concepts

API keys

Secret keys authenticate every request to the Deckle API, SDK, and SMTP relay. Create one per environment, keep it secret, and rotate it when you need to.

Deckle uses secret API keys to authenticate requests. Each key is scoped to a single project and a single environment (Test or Live), so the key you send decides which sandbox — and which data — you touch.

Secret keys only

Deckle does not issue public or publishable keys. Every key starts with sk_live_ or sk_test_ and must stay on your server.

Creating a key#

Keys are managed in the dashboard. You'll see the full key exactly once at creation, so have somewhere safe to paste it before you start.

Open Developers

In the dashboard top-nav, go to Developers.

Go to API keys

Open the API keys tab and choose Create key.

Choose an environment and name

Pick Test or Live, then give the key a descriptive name like production-api or staging. The name is just for you — it helps you tell keys apart later when you rotate or revoke them.

Copy the key

The full key (sk_live_…) is shown once. Copy it and store it in your secrets manager or environment variables now — you cannot view it again.

Using a key#

Pass the key as a bearer token in the Authorization header on every request, or hand it to the SDK when you construct the client.

curl https://app.getdeckle.com/api/v1/emails \
  -H "Authorization: Bearer sk_live_..."

Store the key in an environment variable such as DECKLE_API_KEY and read it at runtime. The same key also works as your SMTP password — see Keep keys secret below.

Test vs live keys#

Every project has two environments, and the key prefix is what selects between them. A sk_test_ key runs in the sandbox; a sk_live_ key sends to real inboxes. Read Projects & environments for the full model.

Prefix	Environment	Can send to
`sk_test_`	Test (sandbox)	SES simulator mailboxes and your own verified domains only
`sk_live_`	Live	Any recipient, from a verified domain

Test keys are safe to experiment with

A test key can only deliver to AWS SES simulator addresses like success@simulator.amazonses.com or to domains you've verified — it can never reach a real inbox. Campaign and broadcast sends always require a live key.

Rotating and revoking#

Keys don't expire on their own. When one is compromised, when a teammate leaves, or on a routine schedule, rotate it. Because a key is shown only once, rotation is a create-then-swap, not an in-place reset.

Rotate a key#

Create a replacement

Create a new key in the same environment with a fresh name.

Deploy the new key

Update DECKLE_API_KEY everywhere it's used and roll out the change.

Revoke the old key

Once traffic is flowing on the new key, revoke the old one from Developers → API keys.

Revoke a key#

Revoking a key is immediate and permanent — every request using it (API, SDK, or SMTP) then fails with a 401. Revoke any key you no longer need or suspect has leaked.

json

{
  "error": "Invalid API key"
}

Keep keys secret#

Treat a secret key like a password: it can send email from your domain, read your contacts, and trigger campaigns. Keep it on your server and out of anything a browser or a repository can see.

Your key is shown only once

Deckle displays the full key a single time at creation and never stores it in a form we can read back — we keep only a SHA-256 hash of the key plus a masked prefix (like sk_live_…a1b2) so you can recognize it in the dashboard. If you lose the key, you can't recover it — create a new one and revoke the old. This same secret key doubles as your SMTP password, so protect it accordingly.

A few rules that keep keys where they belong:

Never ship keys to the client

Keys are server-side only. Don't put them in browser code, mobile apps, or public repos — there are no publishable keys for a reason.

Use environment variables

Load the key from DECKLE_API_KEY (or your secrets manager) at runtime instead of hardcoding it in source.

Next steps#

Send over HTTP

Use your key to send your first email with a raw HTTP request.

Projects & environments

See how Test and Live environments and per-project isolation fit together.