Plainrouter authentication: API secrets and MCP tokens

Plainrouter uses a per-workspace Signals secret for the Signals Conversion API, an account-bound workspace execution token for production MCP tool calls, and a narrowly scoped OAuth management credential for account discovery. Public MCP discovery and the synthetic MCP sandbox require no credential. REST, TypeScript, Python, Ruby, Go, and the CLI are six interfaces to the same Conversion API and all use the same Signals workspace secret.

Which credential should I use?

Goal	Interface	Credential	Scope
Send or read Signal data	REST, TypeScript SDK, Python SDK, Ruby SDK, Go SDK, or CLI	Signals workspace secret	One workspace and its Signals resources
Test an MCP integration with synthetic data	`https://plainrouter.com/mcp/sandbox`	None	Four sandbox-only tools; no tenant data or provider access
Call Plainrouter tools as an agent	MCP or an authorized workspace route	Workspace execution token	One workspace, one Meta ad account, and one Read, Write, or Admin tier
Discover the approved agent context	`GET /api/v1/agent/context`	OAuth management credential	Read-only account discovery
Manage tokens, policies, or approvals in the dashboard	Browser session	Signed-in person’s current workspace role	Interactive UI only

These credentials are not interchangeable. The Conversion API rejects workspace execution tokens and OAuth management credentials. MCP rejects Signals workspace secrets and OAuth management credentials.

Never paste any Plainrouter credential into an agent prompt. Inject credentials through your server-side secret manager or the client’s protected credential configuration.

How do I authenticate the REST API?

Send the Signals workspace secret as a bearer token to the server-side Conversion API at https://plainrouter.com/api/v1:

curl "https://plainrouter.com/api/v1/dashboard/events" \
  --header "Authorization: Bearer $PLAINROUTER_TOKEN" \
  --header "Accept: application/json"

PLAINROUTER_TOKEN must contain the Signals workspace secret. A missing or invalid secret returns HTTP 401.

How do I authenticate the TypeScript SDK?

Install @plainrouter/sdk@0.5.1, then configure the generated client explicitly:

import {
  configurePlainrouter,
  listEvents,
} from "@plainrouter/sdk";

configurePlainrouter({
  signalTrackerSecret: process.env.PLAINROUTER_TOKEN!,
});

const result = await listEvents({
  query: { per_page: 25 },
});

The TypeScript SDK does not read environment variables automatically. Your server must pass the Signals workspace secret through signalTrackerSecret. The property keeps its pre-collapse name for compatibility.

How do I authenticate the Python SDK?

Install plainrouter==0.5.2, then create a client with the Signals workspace secret:

import os

from plainrouter import create_client, list_events

client = create_client(os.environ["PLAINROUTER_TOKEN"])
response = list_events.sync(client=client)

The Python SDK requires Python 3.11 or newer. Each operation module also exposes an asynchronous asyncio method.

How do I authenticate the Ruby SDK?

Install plainrouter-sdk 0.1.1, then create a client with the Signals workspace secret:

require "plainrouter"

client = PlainRouter::Client.new(
  token: ENV.fetch("PLAINROUTER_TOKEN")
)

events = client.operations.list_events(per_page: 25)

The Ruby SDK requires Ruby 3.2 or newer. The client sends the supplied tracker secret as a bearer token and does not read environment variables automatically.

How do I authenticate the Go SDK?

Install github.com/plainrouter/sdk-go@v0.5.2, create the generated client, and attach the Signals workspace secret to the request context:

config := plainrouter.NewConfiguration()
client := plainrouter.NewAPIClient(config)
ctx := context.WithValue(
	context.Background(),
	plainrouter.ContextAccessToken,
	os.Getenv("PLAINROUTER_TOKEN"),
)

report, _, err := client.OperationsAPI.GetEmqReport(ctx).Execute()

The Go SDK requires Go 1.23 or newer. Keep the Signals workspace secret in server-side credential storage.

How do I authenticate the CLI?

The CLI uses the same Signals workspace secret. Current 0.5.x builds call it a tracker token in prompts for compatibility. Store it through the hidden login prompt for an interactive workstation:

plainrouter auth login
plainrouter auth status
plainrouter events list --json

For CI or an ephemeral shell, inject PLAINROUTER_TOKEN through the job’s secret manager before running the command. The CLI does not expose a --token option. An environment token takes precedence over the locally stored token.

How do I try MCP without a credential?

Connect an MCP client to the synthetic test endpoint:

https://plainrouter.com/mcp/sandbox

It exposes get_account_state, get_signal_health, get_performance, and validate_sandbox_event. Every response is synthetic and marked with "sandbox": true. The endpoint reads no tenant data, persists nothing, and contacts no advertising provider. The production endpoint also permits anonymous protocol discovery, tool and resource listing, and reads of static ui:// app shells. Every production tool call and every account-data read still requires an account-bound workspace execution token.

How do I authenticate Plainrouter MCP?

Configure an MCP-compatible client with these exact connection values:

Setting	Value
Transport	Remote HTTP
Server URL	`https://plainrouter.com/mcp`
Authorization	`Bearer <workspace-execution-token>`

A workspace owner issues the token from API in the dashboard for one workspace, one active Meta ad account, one Read, Write, or Admin tier, and a 30, 90, or 365 day expiry. Call get_account_state first. Confirm the returned workspace and Meta ad account before calling another tool. Tool arguments cannot override the account stored with the token.

A Write or Admin token can submit governed proposals, but it does not bypass policy, human approval, provider verification, or account restrictions. A proposal-producing MCP request is not a direct Meta write.

How do I use an OAuth management credential?

An OAuth management credential has one documented agent-facing use:

GET /api/v1/agent/context HTTP/1.1
Host: plainrouter.com
Authorization: Bearer <oauth-management-credential>
Accept: application/json

The route returns the approved read-only account-discovery context. The same credential cannot call MCP tools, Launcher imports, or other agent-authenticated routes. Use a separately issued workspace execution token for MCP after discovery.

Why does a dashboard URL reject my bearer token?

Dashboard settings and approval pages require a signed-in browser session. A valid workspace execution token or OAuth management credential cannot replace that session, even with an active grant or Admin tier. If an automation receives 401 on a dashboard URL, check the requested interface before rotating credentials. Use the documented MCP or API operation with its matching credential, or sign in to complete the interactive action. For grant management, follow the dashboard revocation steps or the separately authorized revoke_grant MCP tool.

Which clients are available?

Client	Package or endpoint	Current version	Authentication
REST	`https://plainrouter.com/api/v1`	Signed OpenAPI `0.5.0`	Signals workspace secret
TypeScript setup	`@plainrouter/sdk`	`0.5.1`	Signals workspace secret passed through `signalTrackerSecret`
Python setup	`plainrouter`	`0.5.2`	Signals workspace secret passed to `create_client`
Ruby setup	`plainrouter-sdk`	`0.1.1`	Signals workspace secret passed to `PlainRouter::Client.new`
Go setup	`github.com/plainrouter/sdk-go`	`v0.5.2`	Signals workspace secret attached to the request context
CLI setup	`plainrouter`, `@plainrouter/cli`, or `plainrouter/tap/plainrouter`	PyPI `0.5.2`; npm `0.5.1`	Stored compatibility-labeled tracker token or `PLAINROUTER_TOKEN`
MCP sandbox	`https://plainrouter.com/mcp/sandbox`	Server `0.3.2`	None
MCP production	`https://plainrouter.com/mcp`	Server `0.3.2`	Workspace execution token for tool calls and account data

The REST contract and all four SDKs expose the signed Conversion API operations. The PyPI and npm CLI distributions expose nine commands and do not include an ingestion-verification command. Use REST, an SDK, or MCP for ingestion verification.

Which credentials must not be confused?

A Signals workspace secret cannot authenticate MCP.
A workspace execution token cannot authenticate the Conversion API.
An OAuth management credential cannot authenticate MCP.
A browser session cannot replace an API or MCP bearer credential.
A same-origin Path B forwarding secret authenticates generated forwarding infrastructure only. It is not an API, SDK, CLI, or MCP credential.
Meta access tokens remain on the Plainrouter server. Do not place a Meta token in a Plainrouter client configuration.

For complete request and response fields, use the Conversion API reference. For token tiers and lifecycle, use Workspace tokens. For available agent tools, use the MCP tool reference. For machine discovery, start with the API resource index or the RFC 9727 API catalog.

Overview

Endpoints

Resources

Plainrouter authentication: API secrets and MCP tokens

Which credential should I use?

How do I authenticate the REST API?

How do I authenticate the TypeScript SDK?

How do I authenticate the Python SDK?

How do I authenticate the Ruby SDK?

How do I authenticate the Go SDK?

How do I authenticate the CLI?

How do I try MCP without a credential?

How do I authenticate Plainrouter MCP?

How do I use an OAuth management credential?

Why does a dashboard URL reject my bearer token?

Which clients are available?

Which credentials must not be confused?

​Which credential should I use?

​How do I authenticate the REST API?

​How do I authenticate the TypeScript SDK?

​How do I authenticate the Python SDK?

​How do I authenticate the Ruby SDK?

​How do I authenticate the Go SDK?

​How do I authenticate the CLI?

​How do I try MCP without a credential?

​How do I authenticate Plainrouter MCP?

​How do I use an OAuth management credential?

​Why does a dashboard URL reject my bearer token?

​Which clients are available?

​Which credentials must not be confused?

Which credential should I use?

How do I authenticate the REST API?

How do I authenticate the TypeScript SDK?

How do I authenticate the Python SDK?

How do I authenticate the Ruby SDK?

How do I authenticate the Go SDK?

How do I authenticate the CLI?

How do I try MCP without a credential?

How do I authenticate Plainrouter MCP?

How do I use an OAuth management credential?

Why does a dashboard URL reject my bearer token?

Which clients are available?

Which credentials must not be confused?