---
title: "Tokens and scopes"
description: "Access levels, expiry, limits, and revocation for MCP tokens."
canonical_url: "https://docs.trytestr.com/docs/mcp/tokens"
markdown_url: "https://docs.trytestr.com/docs/mcp/tokens.md"
last_updated: "2026-11-16"
x_farming_labs_generated_preamble: true
---

# Tokens and scopes
URL: /docs/mcp/tokens
LLM index: /llms.txt
Description: Access levels, expiry, limits, and revocation for MCP tokens.

# Tokens and scopes

## Scopes

| Access level        | Scope                   | Allows                                                                                      |
| ------------------- | ----------------------- | ------------------------------------------------------------------------------------------- |
| Read only (default) | `owner:context:read`    | Read apps, campaigns (including private instructions), reports, conversations, and evidence |
| Read and write      | `owner:workspace:write` | Everything above, plus comments, review decisions, and app and campaign management          |

Write tools are only advertised to write-enabled tokens. Each write also rechecks scope, revocation, owner role, suspension, and ownership when it runs.

<Callout type="info">
  Tokens created before write access existed stay read-only. Create a new token to enable writes.
</Callout>

## Expiry and limits

- Expiry options: **30**, **90** (default), or **365** days, or **Never expires**.
- Non-expiring tokens stay valid until you revoke them.
- You can have up to **20 active tokens** per owner account.

## Who can use a token

A token stops working when:

- it expires or is revoked,
- the account is suspended, or
- the account loses the owner role.

Administrator roles never broaden MCP access.

## Revoke and rotate

Revoke a token from **Account settings → Agent connections**. Revocation takes effect on the next request, including clients that are already connected. To rotate, create a new token, update your client, then revoke the old one. Expired and revoked tokens stay listed for reference.

<Callout type="warn">
  Evidence links that were already issued stay valid for up to 60 seconds after you revoke a token.
</Callout>

## Management API

You can also manage tokens from a signed-in owner session. These endpoints require the browser session, not an MCP token.

| Method   | Path                                  | Body                               | Returns                                |
| -------- | ------------------------------------- | ---------------------------------- | -------------------------------------- |
| `GET`    | `/api/v1/integrations/mcp/tokens`     |                                    | `{ endpoint, tokens }` without secrets |
| `POST`   | `/api/v1/integrations/mcp/tokens`     | `{ name, expiresInDays?, scope? }` | `{ token, metadata }`, shown once      |
| `DELETE` | `/api/v1/integrations/mcp/tokens/:id` | `{}`                               | Revokes idempotently                   |

`expiresInDays` accepts `30`, `90`, `365`, or `null` for no expiry. `scope` defaults to `owner:context:read`.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).
