# API tokens

> An API token in MailCamp is a credential that lets external systems read and write MailCamp data programmatically — for example, syncing contacts from a CRM, triggering campaigns from a webhook, or pulling statistics into a data warehouse.

## What it is

The MailCamp UI is one way to interact with the platform; the API is another. Where a user signs in with email and password, an integration authenticates with an API token. Tokens are scoped to the account that created them, and their access is further constrained by a configurable set of **abilities** (per-resource read or full access).

## Key concepts

- **Token**: a secret string the integration uses to identify itself to MailCamp.
- **Name**: a human-readable description of where the token is used (e.g. "Zapier integration", "data warehouse sync"). Helps with rotation later.
- **Permissions (abilities)**: each token carries a set of permissions that decide what it can do. You can grant read-only or full access on a per-area basis (contacts, campaigns, lists, etc.). A token with no permissions cannot do anything until you grant some.
- **Created at / last used at**: timestamps you can use for auditing and to spot tokens that are no longer in use.
- **Rotation**: tokens can be revoked and replaced at any time without affecting other tokens.

## Common workflows

### Creating a new API token

1. Open **Settings → API tokens**.
2. Choose **New token**.
3. Enter a name describing where the token will be used.
4. Save. The token value is shown **once** — copy it immediately into your secret store. MailCamp does not show it again.
5. Open the new token's **Edit** screen and grant only the permissions the integration needs (for example, read-only on Contacts and Campaigns). Save. Without permissions, the token cannot do anything.

### Revoking a token

1. Open **Settings → API tokens**.
2. Find the token in the list.
3. Choose **Revoke**. Any system using the token will stop working immediately.

### Rotating a token

1. Create a new token with the same label suffixed with a date.
2. Update the integration to use the new token.
3. Once the old token's "last used" timestamp stops advancing, revoke it.

## Limits and edge cases

- The token's secret value is shown only at creation time. If you lose it, revoke the token and create a new one.
- Revoked tokens cannot be reactivated.
- A request that uses an invalid or revoked token will be rejected.
- Rate limits apply to keep the platform stable; integrations should slow down if they're being throttled.
- Treat tokens like passwords — never embed them in front-end code or share them publicly.

## Web routes

Paths use `:id` as the placeholder for a token's identifier.

- `/settings/api` — list of API tokens.
- `/settings/api/new` — create a new token.
- `/settings/api/:id/update` — edit a token's label.
- `/settings/api/usage` — API usage and rate-limit overview.
- `/settings/api/logging` — recent API request logs.

## Related

- [Contacts](/llms/contacts.txt) — most API integrations create or update contacts.
- [Mailing lists](/llms/mailing-lists.txt) — the typical scope of API operations.
- [Campaigns](/llms/campaigns.txt) — can be triggered programmatically.