Copy page

Manage

Handle API tokens securely

Use this guide to protect Project API tokens and Team API tokens throughout their lifecycle. An API token is a credential. Anyone who has the token can use its access until the token expires or is revoked.

Know which token you use

Lettermint has two API token types:

• Project API tokens start with lm_. They send email for one project through the Sending API or SMTP.
• Team API tokens start with lm_team_. They manage team resources through the Team API and can have several abilities.

Use a Project API token when an integration only sends email. Use a Team API token only when an integration must manage team resources.

Store tokens safely

• Store tokens in a secrets manager or an environment variable.
• Use tokens only in server-side applications and trusted devices.
• Keep .env files and local configuration files out of source control.
• Do not put tokens in client-side code, logs, screenshots, support tickets, or shared documents.
• Create a separate token for each integration and environment.

Lettermint shows a new token only once. Copy it to its final secure location when you create it.

Limit token access

Give each token only the access that its integration needs:

• Use a project-scoped token instead of a team-wide token when possible.
• Give Team API tokens only the required abilities.
• Add an IP allowlist when an integration uses stable outbound IP addresses.
• Remove tokens for integrations that are no longer active.
• Review who can view, create, rotate, or revoke tokens.

Rotate a token without downtime

Use this process for planned rotation:

1. Create a new token with the required scope, abilities, and IP restrictions.
2. Store the new token in every application, device, and secrets manager that needs it.
3. Deploy or restart each integration and confirm that it uses the new token.
4. Revoke the old token.
5. Confirm that the old token no longer authenticates.

Do not revoke the old token before the new token is active when you need uninterrupted service. If a token might be exposed, revoke it first and accept the possible interruption.

Respond to an exposed token

Treat an exposed token as compromised. Do not wait for proof that someone used it.

1. Revoke the token immediately. For a Project API token, open the project and select API Tokens. For a Team API token, open Manage team and select API Tokens. If a Lettermint security notification says that the token was automatically revoked, confirm that it is inactive in the dashboard.
2. Create a replacement. Give the replacement only the access and IP restrictions that the integration needs.
3. Update every integration. Replace the token in applications, SMTP clients, devices, deployment settings, environment variables, and secrets managers.
4. Remove the exposed value. Remove it from source code, configuration, logs, tickets, and other shared locations.
5. Review token activity. Check the last-used time, source IP address, and token logs for activity that you do not recognize.
6. Review the affected resources. For a Project API token, review recent email activity. For a Team API token, review changes made with its abilities.

Never reuse an exposed token, even if you remove it from the original location.

If you do not have permission to revoke the token, contact a team member who has the required token permission immediately.

Remove a token from Git

Revoke the token before you change the repository. Removing a token from the latest commit does not remove it from earlier commits, forks, clones, pull requests, or cached views.

Remove the token from the current files and prevent the file from being committed again. If you must remove it from Git history, coordinate the change with all repository contributors. History rewriting changes commit identifiers and can affect open work. See GitHub's guide to removing sensitive data from a repository.

Review activity after an exposure

Check the token details in the Lettermint dashboard:

• Compare the last-used time and IP address with the expected integration.
• Review token logs for unknown requests or denied IP addresses.
• Review email activity for messages that you did not send.
• Check whether a Team API token changed projects, routes, domains, webhooks, members, or suppressions.

Contact help@lettermint.co if you find activity that you do not recognize or need help with the response.

Prevent another exposure

• Keep secret files out of source control with .gitignore.
• Review staged changes before each commit.
• Use secret scanning and push protection in source repositories.
• Use one token per integration so that one exposure has a limited effect.
• Rotate long-lived credentials on a regular schedule.
• Remove inactive tokens after an integration is retired.

Manage tokens

• Project API tokens - Create, restrict, rotate, and revoke sending credentials
• Team API tokens - Create management credentials and limit their abilities
• Team security - Review account and team security controls