API tokens

An API token lets a script or CI job call the API as you. Each token has a scope, an access level, and a 24-hour lifetime. AI agents do not need one: they sign in through the MCP server and appear in the token list as connected agents.

#Scopes

A token never exceeds its owner's access. If you leave a workspace or your role changes, your tokens change with you on the next call.

Some endpoints need a broader scope:

• Your identity, managing API tokens, workspace membership, invitations, renaming or deleting a workspace, billing changes, moving projects, and the fleet need an account token.
• Creating, deleting, and restoring projects and environments needs at least a workspace token.
• A project token also reads its project and that project's usage, filtered to its environment.

The API reference names the narrowest scope for every endpoint.

#Access

• Full access reads and changes resources, within your roles.
• Read-only may call read endpoints only. Use it for dashboards, monitoring, and agents that only investigate.

#Create a token

You can also create tokens with an account-scoped, full-access token: POST /v1/api-tokens, or the create_api_token MCP tool. A token created this way never outlives the token that created it.

Name the token after where it is used. The secret, which starts with wgm_, appears once, right after you create it. Mesh stores only a hash and cannot show it again.

#Lifetime

Every token expires 24 hours after it is created. Create a fresh token for each working day or CI run, and revoke a token as soon as you no longer need it. Expired and revoked tokens stop working at once and disappear from the console's lists.

A connected agent's token is the exception: the agent renews it while in use, and it stops 30 days after the agent last renewed it. Its renews_until field says until when. Disconnect revokes it like any other token.

#Check a token

curl https://mesh.example.com/v1/token \
  -H "Authorization: Bearer $MESH_TOKEN"

{
  "id": "4b6f…",
  "name": "GitHub Actions",
  "scope": "project",
  "access": "full",
  "project_id": "…",
  "environment_id": "…",
  "expires_at": "2026-11-08T09:30:00Z",
  "user_id": "…",
  "email": "you@example.com"
}

#Revoke a token

Choose Revoke next to the token, or call DELETE /v1/api-tokens/{tokenId} (MCP: revoke_api_token). GET /v1/api-tokens lists your tokens, and ?workspace_id= lists a workspace's tokens for its admins. The token creator can always revoke it; workspace admins can revoke any token scoped to their workspace, including project tokens, from the workspace's Settings.

#Keep tokens safe

• Prefer the narrowest scope and read-only access that works.
• Keep secrets in your CI's secret store, never in a repository. The wgm_ prefix lets secret scanners recognize a leaked token.
• last_used_at on each token, and the audit log, show when it was used.