Team API tokens

Create and manage team-level API tokens with granular permissions.

This feature is currently in preview and only available to select teams. Contact support if you’d like early access.

Overview

Team API tokens provide programmatic access to your Lettermint team resources at the team level. Unlike project tokens which are scoped to individual projects, team tokens can access multiple resources across your entire team based on their configured abilities.

Team API tokens are different from project API tokens. Project tokens (format: lm_xxx...) are used for sending emails, while team tokens provide broader access to manage team resources via the API.

Creating API tokens

Team API tokens can be created by team owners from the team settings.

Steps to create a token

1. Navigate to Manage team in your dashboard
2. Go to the API Tokens tab
3. Click the Create token button
4. Enter a descriptive name for your token (e.g., “CI/CD Pipeline”, “Analytics Integration”)
5. Select the abilities you want to grant to this token
6. Click Create to generate your token

After creating a token, make sure to copy it immediately. For security reasons, you won’t be able to see the full token again. Store it securely in your environment variables or secrets manager.

Managing API tokens

Viewing your tokens

All active team API tokens are listed in the API Tokens tab under Manage team. Each token displays:

• Name: The descriptive name you provided
• Abilities: The permissions granted to this token
• Last used: When the token was last used to make an API request
• Created: When the token was created

Regenerating tokens

If you suspect a token has been compromised, you can regenerate it:

1. Click the 3-dots menu next to the token
2. Select Regenerate
3. Confirm the regeneration
4. Copy your new token immediately

Regenerating a token will immediately invalidate the old token. Any integrations using the old token will stop working until you update them with the new token.

Revoking tokens

To remove a token you no longer need:

1. Click the 3-dots menu next to the token
2. Select Revoke
3. Confirm the deletion

The token will be immediately revoked and can no longer be used to access your team.

Token abilities

Team API tokens use a granular permission system based on abilities. When creating a token, you can select which abilities to grant.

Read vs write scopes

Abilities are organized into read and write scopes:

Read abilities allow tokens to:

• View team information and settings
• List team members
• View projects, routes, and domains
• Access message data and statistics
• View webhooks and suppression lists

Write abilities allow tokens to:

• Update team settings
• Create, update, and delete projects
• Manage domains and DNS records
• Create and configure routes
• Manage webhooks
• Add or remove suppression list entries

Available abilities

The following abilities can be granted to team API tokens:

Ability	Scope	Description
read:team	Read	View team information and settings
write:team	Write	Update team settings
read:members	Read	View team members and their roles
read:projects	Read	List and view all team projects
write:projects	Write	Create, update, and delete projects
read:routes	Read	View email routes
write:routes	Write	Create, update, and delete routes
read:domains	Read	View team domains
write:domains	Write	Add, update, and delete domains
read:messages	Read	View message data and delivery statistics
read:webhooks	Read	View webhook configurations
write:webhooks	Write	Create, update, and delete webhooks
read:suppressions	Read	View suppression lists
write:suppressions	Write	Add or remove email addresses from suppression lists

You can select multiple abilities when creating a token. Choose only the abilities your integration needs to follow the principle of least privilege.

Using team API tokens

Team API tokens are used to authenticate requests to the Lettermint API. Include your token in the Authorization header:

cURL

curl -X "GET" "https://api.lettermint.co/v1/team" \
  -H 'Accept: application/json' \
  -H 'Authorization: Bearer YOUR_TEAM_TOKEN'

For a complete API usage guide with detailed examples and common workflows, see the Team API documentation.

Best practices

Security recommendations

• Never commit tokens to version control: Store tokens in environment variables or secrets managers
• Use descriptive names: Name tokens based on their purpose (e.g., “Production CI/CD”, “Monitoring Dashboard”)
• Grant minimal abilities: Only give tokens the abilities they need to function
• Rotate tokens regularly: Regenerate tokens periodically, especially for long-running integrations
• Delete unused tokens: Remove tokens that are no longer needed
• Monitor token usage: Check the “Last used” timestamp to identify inactive or potentially compromised tokens

Token management tips

• One token per integration: Create separate tokens for each service or integration
• Document token usage: Keep a record of which tokens are used where
• Set up alerting: Monitor failed authentication attempts in your logs

Team API tokens have broad access to your team resources. Treat them with the same care as passwords and never expose them in client-side code or public repositories.

Permissions required

Only team members with the Owner role can create, regenerate, or delete team API tokens. This ensures that access to team-level API operations is tightly controlled.

If you need API access but don’t have the Owner role, contact your team owner to either grant you the Owner role or create a token on your behalf.