Issue a token
Sign in as the workspace owner or a current team member and select the workspace your agent should use. The effective tier is capped by your current role in each selected workspace; a requested Write key can have Read access in a workspace where you lack update permission. The page lists and revokes only your own keys. A key can be created before connecting an ad account. The workspace-scoped installation and arrivals tools work without account selection; account reads need an eligible account and active provider connection.- Open Settings → Workspace keys.
- Enter a Name and check Tier: Write is preselected. Choose Read explicitly for supported reporting or diagnostic tools; Actions previews and proposals require Write; new Read keys also cover Actions record reads. Select a 30, 90, or 365 day expiry.
- Under Workspaces, select one or more workspaces. The current workspace is selected by default; this set stays fixed for the key.
- Choose Create key, then Copy the revealed key. It is shown once.
- Configure your MCP client with
https://plainrouter.com/mcpand the key as its bearer credential. The reveal dialog includes Claude Desktop and Claude Code configuration examples. - Call
list_workspacesto inspect authorized workspaces and their effective tiers. If more than one is available, includeworkspace_idon subsequent tool calls. Confirm the returned workspace and intended account withget_account_statebefore account-scoped work.
How does workspace selection work?
Calllist_workspaces with no arguments. It returns only the workspaces available to the execution credential, with workspace_id, workspace_name, ad_account_name and effective tier. A null account name or tier is unknown, not a grant of access.
The first page defaults to 25 workspaces. Use limit from 1–100 and pass the returned integer next_cursor as cursor until it is null. total describes the matching set; truncated: true means more workspaces remain. A short page is not necessarily the complete credential scope.
When the credential has multiple authorized workspaces, include the selected positive integer workspace_id in each workspace-scoped MCP call:
workspace_id can be omitted. Workspace-only reads, such as installation, cookie scan and consent reporting, do not require account_id.
For the Actions API, /workspaces/{workspace}/… selects the workspace. If a query or body also supplies workspace_id, it must agree with that URL. Neither an argument nor the dashboard’s current workspace can widen the credential’s selected set. Create a replacement key to change that set.
How does account selection work?
Pass workspace IDs exactly as returned bylist_workspaces. Booleans, decimal forms, whitespace and leading-zero forms are not canonical selectors. A malformed tool argument or conflicting query/header selector is refused; do not cast arbitrary input to an integer to force access. A refusal does not reveal whether another workspace exists.
For tools that accept account_id, use Plainrouter’s positive integer advertising-account ID, not Meta’s external ad account ID. For example:
Signals reads use the destination binding
get_account_state, get_signal_health, and get_performance use the Meta account bound to this workspace’s Signals destination. Omit account_id to resolve that binding; if supplied, it must identify the same account. Another active team account cannot substitute for it. Reporting through this binding does not authorize Actions against an account owned by another workspace.
If the tool reports no_signals_destination, connect the intended destination. For account_not_bound, check the workspace and bound Meta account rather than trying each account ID. Older bound keys still cannot override their binding.
Actions and creative tools select an eligible account
An eligible account for an unbound key must be owned by the key’s workspace, active, and have an active provider connection. A destination binding to another workspace’s account does not grant access. The key cannot select a workspace outside its authorized set or use an ownerless team account.
Retained inventory uses an explicit account
get_account_inventory and get_inventory_metrics always require the internal Plainrouter account_id. They read retained data for an account available to the workspace, which can include disconnected accounts. Inspect staleness and connection status before using the result. Older account-bound keys still cannot select another account. See account inventory.
How does the Viewer team role affect a key?
Viewer is read-only workspace membership, separate from a key’s requested tier. A Viewer can issue role-capped Read access and inspect authorized data, but cannot edit settings, connect providers, upload creatives or propose advertising changes. Choosing Write does not bypass that role cap. The Read tier can list operations that also require update permission at call time: ingestion verification and feedback submission are refused for a Viewer issuer. Recheck the issuer’s current role as well as the grant when troubleshooting a previously working call.Access tiers
The five Actions read tools and corresponding HTTP endpoints accept an active
read-actions grant, included in newly issued Read and Write keys. Existing grants containing propose-actions remain compatible for reads. Older Read credentials without either operation need replacement or fresh authorization; scopes are not silently expanded.
New keys expose Read and Write, not Admin. Older Admin-tier credentials may still appear in compatibility responses; their tier does not bypass policy, the selected approval mode, provider verification, or account restrictions. A workspace key is not a management key or browser session.
Plainrouter rechecks the issuer’s verified email, current workspace role and the linked grant on requests. An email change pauses that person’s protected access until the new address is verified; verify the account email before troubleshooting a still-valid key. An expired or revoked grant cannot authorize operations even when the key’s own expiry has not passed. If the issuer loses the required role, requests are refused even when the key has not expired. Disconnecting a bound connection revokes its associated agent credentials; reconnecting does not restore a revoked credential. Issue replacement access after reconnection when needed. Feature availability remains separate from key permissions. A key cannot restore retired legacy Launcher operations.
Workspace grants
Each selected workspace has its own grant identifying the credential’s principal, allowed operations and expiry in that workspace. 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 creation responses include a legacygrant_id for the primary workspace. It is not a grant shared by every workspace. Inspect the selected workspace’s Grants section for its own grant; list_workspaces reports effective tiers, not grant IDs. 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 team owner or an authorized team administrator and open Workspace settings → Workspace grants. The section is a bounded current view: live grants, qualifying revocations from the last seven days and up to five recent expired grants. Expand Show … expired to inspect that sample and its total count; this is not an export of the entire grant history. Each grant shows its principal, tier, Live, Expired, or Revoked status, bound token name, and expiry. Expand Exact operations to inspect what it authorizes. Inspect the linked grant here; Settings → Workspace keys lists the key’s status and last use.- Identify the intended principal and bound token before making a change.
- For a live grant, click Revoke, then confirm Revoke grant.
- Confirm the grant now shows Revoked. Expand its Receipt to inspect the audit entry, sequence, and hash prefix.
Rotate or revoke a token
Open Settings → Workspace keys to inspect names, creation time, last use, expiry, and Active, Expired, or Revoked status. To replace a key, create a new one, install it in the client, and verifyget_account_state with the intended account. Then use Delete on the old key and confirm. The current page does not have a Rotate button. If a key is exposed, delete it immediately before preparing its replacement.
Deleting a workspace key revokes its credential and linked grants; the revoked record remains security history. It does not undo earlier provider actions. Issuance and revocation record token.issued and token.revoked metadata without plaintext credentials.
Troubleshoot
The client receives 401 Unauthorized
Check the complete bearer credential, expiry, revocation, grant state, and issuer’s current role. Use a workspace key, not a Management key, OAuth management credential, or Signals Server secret. Older account-bound keys also depend on the bound account remaining available.
A multi-workspace call fails or selects the wrong context
Calllist_workspaces, choose an authorized workspace_id, and include it in each workspace-scoped MCP call. Missing selection is refused when several workspaces are available. On REST routes, remove conflicting workspace selectors or make them agree with the URL. Check the selected workspace’s effective tier before proposing a change.
The tool asks for an account or rejects the selected account
For Signals reads, check the workspace’s Meta destination binding and use that account. For Actions and creative tools, supplyaccount_id when multiple eligible active accounts exist; verify workspace ownership and an active connection. Do not use Meta’s external ID in this field. An older bound key cannot select another account; create a new workspace key when that restriction no longer fits the intended work.
A tool reports insufficient permission
Use Read for supported Signals, account, or creative reads. Actions record reads needread-actions or compatible propose-actions access. Dry runs and proposal-producing tools need Write and their applicable grants. Existing grants retain their issued operations. OAuth refresh does not add newer operations or upgrade the original tier. Create a replacement or complete a fresh authorization with the needed access; do not try to elevate an existing key. Missing feature enablement or provider permissions is separate from its tier.