API keys, scopes and test mode

Keys are passwords with a label

This article is part of the Mailprompt help centre. It covers the key lifecycle and the mistakes that cost people an afternoon.

An API key authenticates a machine. It is not a login session and it does not carry a person's identity, which is why the approval rule still applies: a key can create a draft and request approval, but a human approves. Treat the secret like a password and store it in the client's secret manager rather than in a document or a chat message.

The visible prefix is not the secret. Mailprompt stores a prefix and the last four characters for identification, plus a hash of the full key for verification. That means the list can show you which key is which without ever holding the value.

Creating a key

Open Settings, then API keys and MCP. Choose a label, choose live or test mode, and create. The secret appears once.

A good label names the client and the environment, such as "Reporting script — production" or "Claude Desktop — laptop". A label like "test" becomes useless after the third key. The last-used time in the list tells you whether a key is still in use.

A live key can act on the real account. A test key talks to a synthetic store: reads return example data, writes are accepted and discarded, sends do not happen and credits are not charged. Every test-mode response carries a header that says so, which makes it easy to prove in a client log that a request did not touch production.

Scopes

Scopes decide what an endpoint will accept. The public API documents the scope for each operation. A request with a key that lacks the scope is refused with a forbidden error; it is not silently downgraded.

Use the smallest set. A dashboard that shows results needs results and profile reads, not write scopes. A store connector that posts events needs events write and nothing else. A flow-building integration needs flows read and write, and it still cannot approve. An MCP client used for reading should get read-only scopes.

Scope names are stable and documented. Do not guess one: the error message lists what the endpoint requires. If a client needs a scope that does not exist, the action is not available through the API.

Sending the key

Send the key as an Authorization: Bearer header on every request. The API does not accept a key in the query string; a request that tries gets a specific error code so the mistake is obvious in logs rather than silently accepted.

Do not put a key in a browser application. The public API is server-to-server and has no CORS support. A storefront integration posts to the tracking endpoint instead, which uses its own public identifier rather than an account key.

Rotation and revocation

Rotate a key when a person leaves, when a client is replaced or when a secret may have been exposed. Rotation creates a new secret and keeps the old one valid for a short grace period. Deploy the new value, confirm the client works, then revoke the old key.

If a key is exposed, revoke it first and rotate second. The grace period is a convenience for planned changes, not a reason to leave a leaked credential alive. Revocation takes effect within seconds; a client using the revoked key receives an unauthorized response.

Expiry is a separate control. A key can be given an expiry date when it is created, and an expired key stops working without anyone having to remember to revoke it. Use expiry for temporary integrations and for a contractor's access.

Limits and quotas

Each plan has a requests-per-minute rate and a monthly call allowance. The response includes the rate-limit headers and a retry-after value on a 429. Heavy endpoints cost more than one token, so a burst of expensive calls can hit the limit sooner than the raw request count suggests.

A monthly allowance is separate from the per-minute bucket. Exceeding it returns a quota error rather than a rate-limit one. The credits and billing guide explains the credit side, which is different again: reads are free, AI work and billable writes cost credits.

Keeping keys out of logs

Client errors should log the key prefix and the request id, never the full secret or the Authorization header. Mailprompt's own logs follow the same rule. If you paste a request into a support ticket, redact the header; support can diagnose from the request id.

A secret that appears in a public repository should be treated as compromised even if the repository is deleted. Rewrite history if you can, revoke the key either way, and check the last-used time for calls you did not make.

Next steps

The API reference lists every endpoint and scope, and the MCP setup guide shows how to connect a client with a key or an OAuth connector. If you are choosing who on the team can create keys, the team and roles guide explains the owner and admin permissions.