Plain connector setup
Operator·3 minutes to read
Plain does not fit the "bring your own OAuth app" shape most pages beside this one describe. Its
API documents no OAuth flow at all — no client id, no client secret, no authorization-code
redirect — and therefore no botseon oauth-app set step for it (see
docs/connectors/README.md).
Instead, a Machine User in the Plain workspace holds an API key, and that key is what this
connector's calls carry as a bearer token.
1. Create the key in Plain
- In Plain, go to Settings → Machine Users and add a Machine User. Give it an internal Name (for example "Botseon") and a Public name. Plain's documentation does not say which workspace role may do this, so ask an admin on your Plain workspace.
- On that Machine User, add an API key and grant it the three permissions this connector's
tools need (F-PLUG-1), and nothing else:
thread:read— search and read threads.customer:read— read the customer behind a thread.timeline:read— read the messages and events on a thread.
- Copy the key (it starts
plainApiKey_). Plain shows it once; if it is lost, create a new key on the same Machine User rather than looking for the old one.
2. The tools
Plain's API has one fixed address, https://core-api.uk.plain.com/graphql/v1, so this connector
has no per-installation value to set.
3. What each tool does
| Tool | Reads |
|---|---|
plain.search_threads | Searches threads by text (titles, messages, customer names and emails), or lists them by status (TODO, SNOOZED, DONE), one page at a time. |
plain.get_thread | Reads one thread: title, status, priority and the customer it belongs to. |
plain.get_customer | Reads one customer: name, email and external id. |
plain.list_thread_events | Lists what happened on a thread — chats, emails, notes and status changes — one page at a time. |
Plain limits API keys to 450 requests a minute on its entry plan, 600 on the middle one and 1,000 on the top one, counted per workspace; a member may notice a short pause when a busy workspace reaches it.
4. The gap this page cannot close, and why this connector installs available: false
This connector is read-only. Plain's API can also create customers, open threads and reply to them, and none of that is built: replying would reach a customer, and a connector that has no way for a member to connect it yet has no business holding write tools either.
Its catalogue row (packages/db/seed/catalogue.json) ships available: false. What it is waiting
for is on Botseon's side, not Plain's: a row for plain in API_KEY_CONNECTORS
(packages/core/src/connector-catalog.ts), the table the API-key account path reads to let a member
paste a key on the plugin sheet. Until that row exists, nothing makes a Plain account connected,
so the connector assembles no tools. Plain itself has nothing further to publish.
Plain offers no self-serve EU data region: its API is served from a UK host, and Plain's own guidance is to confirm current residency options with the Plain team if EU hosting is a requirement. Transfers are covered by Standard Contractual Clauses and the UK's International Data Transfer Addendum instead.
Last verified against build 331481c.