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

# Manage workspace tokens and grants

> Issue account-bound MCP tokens, inspect workspace grant permissions, and verify token rotation or grant revocation in Plainrouter.

Workspace tokens are the execution credentials for Plainrouter MCP clients and automations. Each token is bound to exactly one workspace and one active Meta ad account in that workspace.

See [Authentication and clients](/docs/api/authentication) for the canonical
comparison with Signals workspace secrets, OAuth management credentials, and
browser sessions.

Only the workspace owner can issue, rotate, or revoke workspace tokens. An active destination binding can make a Meta ad account visible in another workspace without transferring ownership; issue execution tokens from the owning workspace. A client cannot use the token to select another workspace or advertising account.

## Management and execution credentials

| Credential                  | What it can do                                                                           | Lifecycle                                                        |
| --------------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| OAuth management credential | Read the approved `GET /api/v1/agent/context` discovery route. It cannot call MCP tools. | Short-lived access with refreshable authorization.               |
| Workspace execution token   | Authenticate to MCP and authorized workspace routes for one bound account.               | You choose a 30, 90, or 365 day expiry and rotate it explicitly. |

Management credentials are rejected by default on agent-authenticated routes. The context route is the only read-only exception. Every MCP tool and Launcher file import requires a workspace execution token.

## Issue a token

<Steps>
  <Step title="Select the workspace">
    Switch to the workspace that owns the Meta ad account you want the client to use.
  </Step>

  <Step title="Open the token page">
    Open **API** in the Plainrouter dashboard.
  </Step>

  <Step title="Choose the scope">
    Enter a descriptive name. Select one active advertising account, an access tier, and a 30, 90, or 365 day expiry.
  </Step>

  <Step title="Issue and copy the token">
    Click **Issue token** and copy the full token immediately. Plainrouter shows it only once and cannot recover it later.
  </Step>

  <Step title="Configure the MCP client">
    Add `https://plainrouter.com/mcp` as a remote HTTP MCP server. Configure the client to send the full token as its bearer credential.
  </Step>
</Steps>

The resulting request uses the standard header:

```http theme={null}
Authorization: Bearer <workspace-token>
```

<Warning>
  Treat the token like a password. Do not put it in source control, logs, URLs, screenshots, or agent prompts.
</Warning>

## Access tiers

Legacy Launcher is disabled by default. A Read, Write, or Admin token does not make its tools or file-import route available; the Launcher permissions below apply only where the feature is enabled.

| Tier      | Workspace abilities                                    | MCP access                                                                                                                 |
| --------- | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
| **Read**  | `workspace:read`                                       | Read account, Signals, creative context, and Launcher batch status, and submit the consent-safe Signal verification event. |
| **Write** | `workspace:read`, `workspace:write`                    | Includes read access, can submit governed action and creative proposals, and can create or preview Launcher draft batches. |
| **Admin** | `workspace:read`, `workspace:write`, `workspace:admin` | Uses the same MCP tools as **Write** and can manage token lifecycle and workspace provisioning through authorized APIs.    |

No tier grants wildcard access. **Write** and **Admin** do not bypass action policy, human approval, provider verification, or account restrictions. Proposal-producing MCP tools still create governed proposals rather than direct Meta writes.

Plainrouter rechecks the issuing person's live workspace role on every authenticated request. Read requires current read access, Write requires update access, and Admin requires the owner-level permission used for workspace deletion. A role downgrade immediately caps the token even if its stored expiry has not passed.

<Note>
  Workspace tokens authenticate MCP and authorized workspace routes. They cannot act as an interactive browser session. Sign in to Plainrouter to manage tokens and approvals.
</Note>

To change a token's account or tier, issue a new token and revoke the old one. Plainrouter does not elevate an existing token in place.

## Workspace grants

Each execution credential is linked to a grant that identifies its principal, workspace, allowed operations, and expiry. Plainrouter checks that the grant is active and covers the requested operation, in addition to the credential's existing account and role restrictions.

Token-management responses include `grant_id`. An authorized administrator can use [`revoke_grant`](/docs/mcp/tools#revoke_grant) to stop operations backed by that grant. A human delegator can also revoke their agent's grant. Revocation is scoped to the workspace and recorded as `grant.revoked`; it does not undo earlier provider actions.

### Inspect and revoke a grant in the dashboard

Sign in as the workspace owner and open **Workspace settings → Workspace grants**. Each grant shows its principal, tier, **Live**, **Expired**, or **Revoked** status, bound token name, and expiry. Expand **Exact operations** to inspect what it authorizes. The **API** token list also shows each token's grant tier and status.

1. Identify the intended principal and bound token before making a change.
2. For a live grant, click **Revoke**, then confirm **Revoke grant**.
3. Confirm the grant now shows **Revoked**. Expand its **Receipt** to inspect the audit entry, sequence, and hash prefix.

The receipt records authorization revocation; it is not a Meta execution receipt. Revocation prevents subsequent operations under the grant and does not reverse earlier advertising actions. Grants cannot be edited to add operations; issue a replacement credential when the authorized scope must change.

If no grants appear, confirm the workspace and whether a credential has been issued. If the section is unavailable, check that you are signed in as the owner. An expired or already revoked grant has no live-grant **Revoke** action. If confirmation fails, keep the error and recheck the grant's displayed status before assuming access has stopped.

## Rotate or revoke a token

Open **API** in the dashboard to review active and revoked tokens.

* Click **Rotate** to issue a replacement with the same workspace, account, and tier. Choose a new expiry and copy the replacement immediately. The previous token stops authenticating as soon as rotation succeeds.
* Click **Revoke** to stop a token immediately. Plainrouter retains the revoked record as durable security history.

Issuance and rotation add `token.issued` to the workspace's v2 audit chain. Rotation and revocation add `token.revoked`. Audit events contain token metadata and scope, never the plaintext credential.

## Troubleshoot

### The client receives `401 Unauthorized`

Confirm that the client sends the complete token as a bearer credential. Expired or revoked tokens are rejected. Also inspect the linked grant: an unexpired token cannot authorize operations after its grant is revoked. A token also stops authenticating if its bound account, Meta connection, or agent principal is no longer active, or if the issuer's current workspace role no longer covers its tier.

### A tool reports insufficient permission

Use **Read** for account, Signals, creative-library, and Launcher batch-status reads. Use **Write** or **Admin** for tools that submit action or creative proposals or create and preview Launcher batches. Issue a new token when you need a different tier.

### The wrong account appears

Revoke the token and issue another one for the correct advertising account. MCP tool calls cannot override the account stored with the token.

### You cannot open the token page

Only the workspace owner can manage tokens. Confirm that you selected the intended workspace and that its Meta account connection is active.