> ## 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.

# Workspace tokens

> Issue, use, rotate, and revoke owner-managed bearer tokens for one workspace and Meta ad account.

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/auth) for the canonical
comparison with Signal tracker secrets, OAuth management credentials, and
browser sessions.

Only the workspace owner can issue, rotate, or revoke workspace tokens. 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">
    In the PlainRouter sidebar, open **Account** → **API**.
  </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

| 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.

## Rotate or revoke a token

Open **Account** → **API** 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. 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.