API Key Management

Create, list, and revoke API keys for authenticating with mail-catcher.

mail-catcher uses Bearer token authentication. API keys are managed through a CLI tool that communicates directly with DynamoDB.

How keys work

1. You create a key using the provisioning script
2. A random 32-byte token is generated and displayed once
3. The token is hashed with SHA-256 and stored in the ApiKeysTable in DynamoDB
4. The plain-text token is never stored. Save it immediately

When you make API requests, the token is hashed and compared against stored hashes. If a match is found, the request is authenticated.

Create a key

bun run provision --create --name my-project

Output:

API key created:
  Name:   my-project
  Key ID: a1b2c3d4
  Token:  9jkLmN0pQ1rSt2uV3wX4yZ5aB6cD7eF8gH9iJ0k=

Save this token. It cannot be retrieved again.

Use the --name flag to label keys by project or environment for easier management.

List keys

bun run provision --list

Output:

API Keys:
  my-project          a1b2c3d4          2024-03-10T12:00:00Z
  staging-tests       e5f6g7h8          2024-03-08T09:30:00Z

This shows the name, key ID, and creation date. The token itself is not retrievable.

Revoke a key

bun run provision --revoke a1b2c3d4

This immediately removes the key hash from DynamoDB. Any request using the revoked token will return 401 UNAUTHORIZED.

Best practices

• One key per project: create separate keys for each project or environment that uses mail-catcher. This makes it easy to revoke access for a single consumer without affecting others.
• Rotate keys periodically: create a new key, update your project's configuration, then revoke the old key.
• Store tokens securely: use environment variables or a secrets manager. Never commit tokens to version control.
• Use descriptive names: names like frontend-e2e, staging-ci, or project-x-prod make it clear what each key is for when listing them.