> ## Documentation Index
> Fetch the complete documentation index at: https://docs.molesignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# API tokens and service accounts

> Create and revoke API tokens for scripts, collectors, and AI clients, and give long-running automation an identity of its own.

An API token lets a program call MoleSignal without signing in. A service account is an identity
for such a program: it cannot sign in, and its tokens act as the account. Open
**Identity & Access → API tokens** or **Service accounts**.

## Token types

| Type | Acts as | Created on |
| - | - | - |
| **Personal API token** | The signed-in user, with the role chosen for the token. | **API tokens** |
| **Service Account API token** | A service account, with the role of the account. | **API tokens** or **Service accounts** |
| **Default intake token** | The write-only `intake` role. | **Datasource**. See [Intake tokens](https://docs.molesignal.com/en-US/intake#intake-tokens). |
| **RUM client token** | The write-only `rum_client` role, bound to one RUM application. | **Datasource**. See [Intake tokens](https://docs.molesignal.com/en-US/intake#intake-tokens). |

A token has the form `ms_<prefix>_<secret>`, and a RUM client token `msrum_…`. The prefix finds the
token, and only a hash of the secret is stored. Send a token as a bearer credential, like a login
session:

```http theme={null}
Authorization: Bearer ms_…
```

A token cannot enter the `_sys` organization.

## Create an API token

1. Open **API tokens** and select **Create API token**.
2. Enter a **Name**, for example `collector-production`.
3. Choose the **Principal**: **Current user**, or a service account.
4. Choose the **Role**. A token of a service account inherits the role of the account. A personal
   token takes **Default intake (write only)** or an organization role. The role cannot hold a
   permission that the creator lacks.
5. Set **Expires in days**: 365 by default, at most 1825. Leave it empty for a token that never
   expires.
6. Select **Create token**, then **Copy token**. The token is shown only this once.

The list shows each token with its prefix, principal, role, type, status, expiry, and last use.
**Revoke** stops a token at once and for good.

Listing tokens requires `api_tokens.read`, and creating or revoking them requires
`api_tokens.manage`.

## Service accounts

Use a service account for a collector, a CI pipeline, an integration, or an AI agent that runs
without a person. Then a member leaving the workspace never breaks the automation.

1. Open **Service accounts** and select **Create service account**.
2. Enter a **Name**, for example `deployment-automation`, a **Description**, and a **Role**.
3. Select **Create account and token**, and copy the initial API token. It expires in 365 days and
   is shown only once.

Select an account to manage it:

| Action | Effect |
| - | - |
| **Save changes** | Keeps a new name, description, or role. Every token of the account follows the role. |
| **Manage API tokens** | Opens **API tokens** filtered to the account, to create more tokens or revoke one. |
| **Disable** / **Enable** | A disabled account and all its tokens stop authenticating until it is enabled again. |
| **Delete** | Removes the account and revokes all its tokens. It cannot be undone. |

The **Principal ID** of the account identifies it in audit records and access grants. Reading service
accounts requires `service_accounts.read`, and changing them requires `service_accounts.manage`.

## Choose a token

| Caller | Recommended token |
| - | - |
| A collector or an agent that sends telemetry | The default intake token, or a service account token with the `intake` role. |
| Browser or mobile code that sends RUM data | The RUM client token of the application. It is visible to end users. |
| CI that reports deployments | The default intake token, which also holds `apm.deploy`. |
| Automation that reads data or changes resources | A service account token with a narrow [custom role](https://docs.molesignal.com/en-US/identity/roles.md#roles). |
| An MCP client or a script run by a person | A personal API token with an expiry. |

A login session expires after 24 hours by default (`[auth].token_ttl_secs`), so never give one to a
sender that runs continuously.

## Tokens API

| Operation | Endpoint | Permission |
| - | - | - |
| Issue a token | `POST /api/v1/auth/tokens` | `api_tokens.manage` |
| List tokens | `GET /api/v1/auth/tokens` | `api_tokens.read` |
| Revoke a token | `DELETE /api/v1/auth/tokens/{id}` | `api_tokens.manage` |

See [Issue an API token](https://docs.molesignal.com/en-US/api/auth/issue-token.md), [List API tokens](https://docs.molesignal.com/en-US/api/auth/list-tokens.md), and
[Revoke an API token](https://docs.molesignal.com/en-US/api/auth/revoke-token.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.