Live and test keys
There are exactly two environments, and a key belongs to one of them for life:
| Prefix | |
|---|---|
lk_live_ |
Real sends, real billing, real limits |
lk_test_ |
The whole request path runs, nothing leaves the platform |
Create a test key by passing "test": true:
{ "label": "ci", "scopes": ["send:write"], "test": true }
Same URL, same code
Both kinds use https://api.lockally.com. There is no separate sandbox host
and no environment parameter. Swapping the key is the whole of the change, so
the code path you exercise in tests is the one that runs in production.
What a test key actually does
A send with a test key is accepted, validated and recorded exactly as a live one. Then, instead of handing it to the mail server:
- it is stored, so you can inspect it
- a simulated
delivery.deliveredwebhook fires, carrying"test": true - the response is still
202, but with"status": "delivered"rather than"queued", because for a test key the outcome is already final - the
message_idends@test.lockally.com - nothing counts against your rate cap, monthly allowance or send units
So the full loop runs, including your webhook handler, without mail reaching anybody.
Inspect what it captured with GET /v1/sandbox/messages, and force a different
outcome with POST /v1/sandbox/messages/{id}/simulate when you want to exercise
your bounce handling.
The one place test is more permissive
Sender authorisation. A live key must send from a verified domain (api mode) or
a mailbox or alias on one (business and both). A test key may send from any
address, and the response carries a warning naming the domain to verify.
That exception exists because the check ran before the test-mode divert, so a workspace with no verified domain could not make a single test call, which was 23 of the 27 api-mode workspaces on the platform.
It is the only divergence between the two kinds of key beyond delivery itself, and it is reported in the response rather than left to be discovered on the first live send.
What a test key will not do
Test mode suppresses delivery. It does not make the rest of your workspace a
copy, so reads and writes are against real data, and POST /v1/templates
creates a real template.
Irreversible operations are refused with 403 Not allowed on a test key:
DELETE on a real resource, anything under /v1/billing/, add-on
cancellation, and closing the account. Deletes that testing needs stay
allowed: webhook endpoints, scheduled messages, suppressions and drafts.
The two cannot be mixed
A key registered as live cannot be presented in lk_test_ form, or the
reverse. The mismatch fails authentication:
{
"status": 401,
"title": "Invalid API key",
"detail": "Key mode (live/test) does not match its registration."
}
This matters more than it looks. The failure mode it prevents is a staging deployment configured with a live key and quietly mailing real customers. Here that cannot happen by accident: the prefix is part of the secret, so a key pasted into the wrong environment fails loudly on the first request rather than succeeding and sending.
Make the prefix an assertion in your deployment. A one-line check that
staging holds a key beginning lk_test_ is the cheapest safety you will ever
add.
A key cannot be converted
Live and test is fixed at creation, like everything else about a key. Promoting something from staging to production means issuing a live key, not flipping a flag.
What test keys are not
Not a separate account. A test key belongs to the same tenant, sees the same domains, templates and suppression list, and writes to the same data. It is isolated in delivery and billing, not in data.
Not free of the plan check. API keys are a plan feature, so an account without API access cannot use a test key either.
Not a way to test deliverability. Nothing reaches a real mail server, so a test send proves your integration works and tells you nothing about whether your mail would arrive.