Skip to main content
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 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

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

1

Select the workspace

Switch to the workspace that owns the Meta ad account you want the client to use.
2

Open the token page

Open API in the Plainrouter dashboard.
3

Choose the scope

Enter a descriptive name. Select one active advertising account, an access tier, and a 30, 90, or 365 day expiry.
4

Issue and copy the token

Click Issue token and copy the full token immediately. Plainrouter shows it only once and cannot recover it later.
5

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.
The resulting request uses the standard header:
Treat the token like a password. Do not put it in source control, logs, URLs, screenshots, or agent prompts.

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