Plainrouter authentication: server secrets and workspace keys

Plainrouter uses a per-workspace Server secret for the Signals Conversion API, a Workspace key for production MCP tool calls and the Actions API, a Management key for developer management operations, and a separate OAuth management credential for account discovery. Public MCP discovery requires no credential. The unauthenticated sandbox is retired. Retrieving a production prompt requires a workspace key. The Signals REST endpoints, TypeScript, Python, Ruby, Go, and the CLI are six interfaces to the same Conversion API and all use the same Server secret.

Does email verification affect my keys?

Yes. Workspace and Management key authentication checks the issuing person’s verified email as well as current access. An email change pauses that person’s protected account and agent access until the new address is verified. Verify the current address before replacing a seemingly valid key; verification cannot restore expired or revoked credentials. Manage verification and optional two-factor sign-in.

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	Server secret	One workspace and its Signals resources
Call Plainrouter tools as an agent	MCP or an authorized workspace route	Workspace key	Fixed selected workspace set, role-capped tier per workspace, and an eligible account selected per account-scoped call
Submit or inspect Actions	Actions API and MCP Actions reads	Read or Write Workspace key: `read-actions` for reads, `propose-actions` for previews/proposals	One authorized workspace per call and selected eligible account
List accessible workspaces and manage your workspace keys	Management API	Management key	Limited by its owner’s current access and role; not an MCP credential
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 keys and OAuth management credentials. MCP rejects Server secrets, Management keys, 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 Server 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 Server secret. A missing or invalid secret returns HTTP 401. For action proposals, status, policy, and decision receipts, use the separate Actions API authentication and account-selection steps.

Where do I manage the Signals API secret?

Sign in as the workspace owner, select the intended workspace, and open Settings → Workspace → Server secret after Signals is configured. This secret authenticates Signals REST, SDK, and CLI calls; workspace keys have their own Settings → Workspace keys page.

Rotate without interrupting your integration

Choose Rotate and copy the replacement immediately into your server-side secret manager. The replacement is shown once.
Update each integration and verify a read request, such as the event-list request above, with the replacement. Your current secret continues working while a replacement is pending.
Choose Confirm after all integrations use the replacement. Confirmation retires the previous secret.

Discard a pending replacement

If you lose the replacement before finishing rotation, choose Discard, then confirm Discard pending replacement. This cancels only the pending secret; your current secret keeps working. Cancel or Escape closes the dialog without discarding anything. Anything already using the pending replacement will stop authenticating after you discard it. Restore those integrations to the current secret before discarding, or prepare to update them during a new rotation. Then choose Rotate again, save the new replacement, verify it, and Confirm when ready. The page cannot reveal a lost secret again. After discarding, Replacement pending disappears and Rotate becomes available. Verify a read with the current secret if you need to confirm integration access. Discard does not change the publishable browser key or the current server secret.

Revoke a lost or exposed secret

Choose Revoke and confirm the warning. The current secret and any pending replacement stop working immediately, and Plainrouter issues a new secret. Copy it once, update your integrations, and verify authentication again. Expect old credentials to return 401. Use Discard when only the pending replacement should be canceled. Use Revoke when the current secret must stop working, including when it is exposed. Keep secrets out of browser code. The Signals snippet uses a publishable key instead.

How do I authenticate the TypeScript SDK?

Install @plainrouter/sdk@0.10.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 Server secret through signalTrackerSecret. The property keeps its pre-collapse name for compatibility.

How do I authenticate the Python SDK?

Install plainrouter==0.10.1, then create a client with the Server 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.6.1, then create a client with the Server 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.7.1, then create the client with the Server secret:

client := plainrouter.New(os.Getenv("PLAINROUTER_TOKEN"))
report, _, err := client.Operations.GetEmqReport(context.Background()).Execute()

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

How do I authenticate the CLI?

The CLI uses the same Server secret and retains the name “tracker token” in its login prompt. 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.

What can I discover without a credential?

https://plainrouter.com/mcp permits public protocol discovery, tool/resource/prompt listing and reads of static ui:// app shells. Retrieving a prompt with prompts/get, calling a tool, and reading account data require workspace authorization. Account-scoped reads additionally require access to the selected account. The old unauthenticated sandbox returns HTTP 410 with sandbox_retired for API and MCP protocol requests. Move existing integrations to authenticated access; anonymous discovery or a browser redirect is not a substitute for a successful workspace read.

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 or member creates a key in Settings → Workspace keys for one or more selected workspaces, a requested Read or Write tier capped by their role in each workspace, and a 30, 90, or 365 day expiry. The selected set is fixed at creation. Call list_workspaces to inspect the authorized set and effective tiers. Include workspace_id on subsequent MCP calls when more than one workspace is available. For account-scoped work, call get_account_state first. Confirm the returned workspace and Meta ad account before continuing. For installation before connecting Meta, use get_install_instructions and confirm its workspace. Signals reads use the workspace’s bound Meta destination; Actions and creative calls require account_id when eligible-account selection is ambiguous. Older account-bound keys cannot override their binding. See account selection.

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

Where do I create a Management key?

Open Settings → Management keys, enter a name, select a 30, 90, or 365 day expiry, and choose Create key. Copy it once into developer-side secret storage. Use Delete to remove an obsolete key. The table shows creation, last use, expiry, status, and Created by; a team owner can manage team members’ keys where permitted. Management keys authenticate the four management operations below under the key owner’s current membership and role. Give agents a workspace key for MCP instead. A Management key is not the OAuth management credential described below and cannot authenticate the agent-context route, Signals Conversion API, or human approval pages.

How do I use the management API?

Use a Management key to list accessible workspaces and create, list, or revoke your own workspace keys. These operations do not create workspaces or change ads. The /tokens paths retain their API name even though the dashboard calls the credentials workspace keys. Before starting, create a Management key, load it into PLAINROUTER_MANAGEMENT_KEY through your secret manager, and confirm your current membership in the workspace’s team. Do not use a workspace key or browser session as the management API credential. Use the base URL https://plainrouter.com/api/v1 for these paths:

Method	Path	Result
`GET`	`/management/workspaces`	`200` with `workspaces`: workspace IDs, names, and team IDs/names for your current memberships and owned teams.
`GET`	`/workspaces/{workspace}/tokens`	`200` with `access_tokens`: your keys in that workspace, including revoked records, without plaintext secrets.
`POST`	`/workspaces/{workspace}/tokens`	`201` with the new plaintext `token` and `access_token` metadata.
`DELETE`	`/workspaces/{workspace}/tokens/{token}`	`204` with no body after revoking your key and its grant.

1. Find the workspace

curl --fail-with-body https://plainrouter.com/api/v1/management/workspaces \
  --header "Authorization: Bearer $PLAINROUTER_MANAGEMENT_KEY" \
  --header 'Accept: application/json'

Choose the returned workspace’s integer id. It is different from the advertising-account ID used in MCP calls. The examples below use workspace ID 42; replace it with your selected ID.

2. Create a workspace key

curl --fail-with-body https://plainrouter.com/api/v1/workspaces/42/tokens \
  --header "Authorization: Bearer $PLAINROUTER_MANAGEMENT_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"name":"Account reporting","tier":"read","expires_in_days":90}'

Field	Accepted value
`name`	Required string, up to 255 characters.
`tier`	Requested `read` or `write`. Each workspace’s effective grant is capped by the issuer’s current role.
`expires_in_days`	`30`, `90`, or `365`.
`workspace_ids`	Optional nonempty array of distinct accessible workspace IDs. Omit it to use the workspace in the URL. Each grant is capped to your current role.

The new key is scoped to the submitted workspace set and has no fixed ad-account binding. For example, add "workspace_ids":[42,43] to authorize those two workspaces. Both must be accessible to the issuer. Do not send an account ID when issuing it; follow account selection when using it. The response contains a secret. Capture token directly into protected client configuration or secret storage and retain access_token.id for lifecycle operations. Plaintext is returned only on creation; the response uses Cache-Control: no-store, private. Keep it out of terminal recordings and request/response logs. A repeated POST creates another key; do not treat issuance as an idempotent retry. Call list_workspaces with the issued execution key to inspect effective workspace tiers. The creation response’s legacy access_token.grant_id identifies the primary grant; it does not enumerate every selected workspace’s grant. An owner can inspect each workspace’s Grants section. Verify the new workspace key with get_account_state, supplying account_id when required. Confirm the returned workspace and Meta ad account before any proposal. Use the new workspace key for that MCP call, not the Management key.

3. List or revoke your workspace keys

curl --fail-with-body https://plainrouter.com/api/v1/workspaces/42/tokens \
  --header "Authorization: Bearer $PLAINROUTER_MANAGEMENT_KEY" \
  --header 'Accept: application/json'

Each access_tokens item includes id, name, tier, abilities, last_used_at, expires_at, revoked_at, and the historical rotated_from_token_id. Listing does not expose another member’s keys or recover a secret. Use the token record’s integer id, not its plaintext value or grant ID, to revoke it:

curl --fail-with-body --request DELETE \
  https://plainrouter.com/api/v1/workspaces/42/tokens/123 \
  --header "Authorization: Bearer $PLAINROUTER_MANAGEMENT_KEY" \
  --header 'Accept: application/json'

Replace 123 with your key’s record ID. A successful response has no body. List again to verify revoked_at is populated. To replace a key, create and verify its replacement before revoking the old one; there is no rotation endpoint. Deleting or expiring a Management key does not revoke workspace keys it previously issued. Revoke each workspace key separately when access should end. Removing the issuer’s membership or reducing their role also changes what their credentials can authorize.

Why does a management request fail?

Result	Check
`401`	Use a live Management key created from the current settings page. Workspace keys, OAuth credentials, expired/revoked keys, and older unmarked personal tokens do not qualify.
`403`	Recheck current team membership and whether your role permits the requested tier. Membership is checked on each request.
`404`	Check the workspace ID and token ID. Another member’s token is not available through your management credential.
`422`	Check name, tier, expiry, and that a key being revoked belongs to the selected workspace.

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 key for MCP after discovery.

Why does a workspace request return 404?

On documented workspace-scoped machine routes, a missing, inaccessible or non-canonical workspace selector returns HTTP 404 with error.code: "api_route_not_found". A credential can be valid while the requested workspace is unavailable to it. This response does not reveal whether another workspace exists. Use the exact positive integer ID returned by discovery. Leading zeros, signs, spaces, decimal forms and booleans are not canonical workspace path IDs. A workspace_id query or body selector matters only on routes that read it; it cannot widen credential access. A foreign or malformed entry in a workspace_ids selection is a field-validation error rather than a way to enumerate workspaces.

Confirm the route’s credential type and intended workspace locally.
Copy the authorized ID from workspace discovery and check both the URL and any documented selector.
Inspect the response code and body together. A 403 for an accessible workspace’s missing operation is different from workspace 404; an Actions receipt_not_available is a separate scoped response. Do not retry neighboring IDs or infer deletion from a generic 404.

The current public contract governs these server responses even if an older generated client describes a narrower error union. See Actions receipts and Workspace key access. MCP workspace selectors follow the same canonical-ID boundary. Pass the integer from list_workspaces; a boolean, padded or leading-zero value is not a valid alternative. Correct both tool arguments and documented query/header selectors. Workspace selection explains the scope rules.

Why does a dashboard URL reject my bearer token?

Dashboard settings and approval pages require a signed-in browser session. A valid Workspace key or OAuth management credential cannot replace that session, even with an active grant or Admin tier. On an accessible session route, a bearer header causes 401 even when a valid browser session cookie is also present. Remove the Authorization: Bearer ... header from browser-session requests; check any proxy or client that adds it automatically. Signing in again does not make a bearer header valid on a session route. 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
Signals REST	`https://plainrouter.com/api/v1`	Signed OpenAPI `0.5.0`	Server secret
TypeScript setup	`@plainrouter/sdk`	`0.10.1`	Server secret passed through `signalTrackerSecret`
Python setup	`plainrouter`	`0.10.1`	Server secret passed to `create_client`
Ruby setup	`plainrouter-sdk`	`0.6.1`	Server secret passed to `PlainRouter::Client.new`
PHP setup	`plainrouter/sdk`	`0.4.1`	Server secret passed to `Plainrouter\Client`
Go setup	`github.com/plainrouter/sdk-go`	`v0.7.1`	Server secret passed to `plainrouter.New`
CLI setup	`plainrouter`, `@plainrouter/cli`, or `plainrouter/tap/plainrouter`	PyPI `0.10.1`; npm `0.10.1`	Stored compatibility-labeled tracker token or `PLAINROUTER_TOKEN`
MCP production	`https://plainrouter.com/mcp`	Server `0.4.2`	Workspace key for tool calls and account data

The REST contract and all five 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 Server secret cannot authenticate MCP.
A Workspace key 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

Sandbox retirement

Plainrouter authentication: server secrets and workspace keys

Does email verification affect my keys?

Which credential should I use?

How do I authenticate the REST API?

Where do I manage the Signals API secret?

Rotate without interrupting your integration

Discard a pending replacement

Revoke a lost or exposed secret

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?

What can I discover without a credential?

How do I authenticate Plainrouter MCP?

Where do I create a Management key?

How do I use the management API?

1. Find the workspace

2. Create a workspace key

3. List or revoke your workspace keys

Why does a management request fail?

How do I use an OAuth management credential?

Why does a workspace request return 404?

Why does a dashboard URL reject my bearer token?

Which clients are available?

Which credentials must not be confused?

​Does email verification affect my keys?

​Which credential should I use?

​How do I authenticate the REST API?

​Where do I manage the Signals API secret?

​Rotate without interrupting your integration

​Discard a pending replacement

​Revoke a lost or exposed secret

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

​What can I discover without a credential?

​How do I authenticate Plainrouter MCP?

​Where do I create a Management key?

​How do I use the management API?

​1. Find the workspace

​2. Create a workspace key

​3. List or revoke your workspace keys

​Why does a management request fail?

​How do I use an OAuth management credential?

​Why does a workspace request return 404?

​Why does a dashboard URL reject my bearer token?

​Which clients are available?

​Which credentials must not be confused?

Does email verification affect my keys?

Which credential should I use?

How do I authenticate the REST API?

Where do I manage the Signals API secret?

Rotate without interrupting your integration

Discard a pending replacement

Revoke a lost or exposed secret

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?

What can I discover without a credential?

How do I authenticate Plainrouter MCP?

Where do I create a Management key?

How do I use the management API?

1. Find the workspace

2. Create a workspace key

3. List or revoke your workspace keys

Why does a management request fail?

How do I use an OAuth management credential?

Why does a workspace request return 404?

Why does a dashboard URL reject my bearer token?

Which clients are available?

Which credentials must not be confused?