---
title: "API keys: live, test, scoping and rotation"
description: "Two modes, per-agent scoping for blast-radius control, and what to do when a key leaks."
url: https://help.mails.ai/en/articles/20-api-keys-live-test-scoping-and-rotation
collection: "Account, keys and billing"
updated: 2026-10-10
language: en
---

# API keys: live, test, scoping and rotation

Two modes, per-agent scoping for blast-radius control, and what to do when a key leaks.

![Mails.ai — API keys: live, test, scoping and rotation](https://staticfiles.gleap.io/p6a77ce6bbe980ea9dbca1955/ftKshl3xtF8xMWpHGRCx0MsD8bATcqDrbnnMGJnMqp6P7XKtRcJ9qOPtUqiCfeaTZl5fK40mTCD.png)

Keys are bearer tokens for `api.mails.ai`. A key is shown in full exactly once, at creation; after that only its prefix is visible, because we store a hash and genuinely cannot recover it for you.

![The API keys page with two live keys and one test key](https://staticfiles.gleap.io/p6a77ce6bbe980ea9dbca1955/oY0F6e7l8qqW3m5ukeJFSb9mGXymrKBXH1Y6FL70Un9Yppuiezyj5eyCQCy3RKI9FEqsGn2L79c.png)

## Two modes

-   `mk_live_...` — real sends, real billing.
    
-   `mk_test_...` — the same calls, events and webhooks, but nothing is transmitted and nothing is billed. Quota, suppression and rate-limit checks are skipped, and a message the firewall would refuse comes back with a warning instead.
    

## Scoping

A key carries scopes: `send` sends mail, `read` reads it, `draft` writes drafts but can never send or schedule one, and `manage` changes the workspace, from agents and keys to webhooks, domains and billing. A key can also be bound to a **single agent**, with the **Agent** choice when you create it in the dashboard or `agent_id` through the API. A bound key sends as that agent only and reads only its mail: another agent's messages and threads answer `404`. That is what you want for the service that only ever sends receipts. Keys are capped per plan: 10 on Free, 50 on Pro, 200 on Scale; revoked keys do not count.

## Rotation

1.  Create the new key.
    
2.  Deploy it.
    
3.  Watch **Last used** on the old key until it stops moving.
    
4.  Revoke the old key.
    

Revoking is immediate and cannot be undone. If a key has leaked, revoke first and reorder those steps — a few failed requests are cheaper than an open door. Anything the key had scheduled is not sent when it comes due: it fails with `scheduling_key_revoked`, so schedule it again with the new key if it should still go.

[Manage API keys](https://app.mails.ai/api-keys)
