Personal API tokens

Named, expiring, revocable tokens for CI, scripts and the CLI: how to create, use and revoke them, and what a token cannot do.

What a token is

A personal API token is a named credential for programmatic access: a CI job, a script, an unattended agent. It acts as your account until it expires or you revoke it.

On your own machine, mlcl login is still the simplest path. Use a token where nobody is there to approve a browser prompt.

Create one

In the app, open the settings panel, expand API tokens, name the token, pick an expiry (30, 90, 180 or 365 days) and choose Create token. From the CLI, signed in with mlcl login:

mlcl token create ci --expires-in-days 90
mlcl token create nightly-backup --json | jq -r .token   # only the token, for scripts
Careful

The token is shown once, when it is created. Put it in your CI secret store right away. If you lose it, revoke it and create a new one.

Use it

The CLI and the MCP server read MOLECULE_TOKEN ahead of any stored login:

export MOLECULE_TOKEN=<token>
mlcl deploy --project <id> --follow

Anything that speaks HTTP sends it as a bearer token to the platform API:

curl -H "Authorization: Bearer $MOLECULE_TOKEN" https://api.molecule.dev/api/projects
Tip

In GitHub Actions or GitLab CI, store the token as a secret and expose it to the job as MOLECULE_TOKEN.

List and revoke

mlcl token list              # id, name, created, expires, last used (also --json)
mlcl token revoke ci         # by name or id

Or choose Revoke next to the token under API tokens in the settings panel. A revoked token stops working within seconds.

Limits

  • A token expires after at most 365 days (90 by default). There are no tokens that never expire.
  • Up to 25 active tokens per account, and up to 10 new tokens a day.
  • Names are 1 to 60 characters and unique among your tokens.
  • Creating and revoking tokens needs a signed-in session (the app, or mlcl login), not a token. Your account email must be confirmed.

What a token cannot do

A stolen token should not be able to take the account over or outlive its revocation, so a request made with a token is refused when it tries to:

  • change your password, email or profile, or manage two-factor authentication;
  • create or revoke API tokens;
  • list or sign out your devices, or approve an mlcl login;
  • create project API keys or vault credentials, or invite teammates or change a member’s role;
  • add or change AI model providers or model settings, or add or change project hooks;
  • change billing, the plan or the spend cap, top up the balance, or open the billing portal;
  • push to a repository, import one, or set an SSH key (the stored GitHub or GitLab credential);
  • delete the account.

Do those from the app while signed in. Everything else your account can do, the token can do, so treat it like a password.