Skip to main content
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
Create team API token form showing name and abilities selection.
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
List of team API tokens with their names, abilities, and usage information.

​
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:
AbilityScopeDescription
read:teamReadView team information and settings
write:teamWriteUpdate team settings
read:membersReadView team members and their roles
read:projectsReadList and view all team projects
write:projectsWriteCreate, update, and delete projects
read:routesReadView email routes
write:routesWriteCreate, update, and delete routes
read:domainsReadView team domains
write:domainsWriteAdd, update, and delete domains
read:messagesReadView message data and delivery statistics
read:webhooksReadView webhook configurations
write:webhooksWriteCreate, update, and delete webhooks
read:suppressionsReadView suppression lists
write:suppressionsWriteAdd 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.