beehiiv connector setup

This page is the setup half: getting a beehiiv OAuth app for this deployment and entering its client id and secret. Authorising a connection afterwards is the Authenticate control on the plugin sheet, which sends the member to beehiiv. What the connector does for a member is on docs/using/connectors/beehiiv-api.md; the vendor facts, with their sources, are in docs/research/connectors/beehiiv-api.md.

The plugin slug is beehiiv-api. The catalogue's beehiiv tile is beehiiv's own hosted MCP server, a different plugin that needs none of this.

1. Get the OAuth app from beehiiv

beehiiv does not have a self-serve app console: "For more information about registering an OAuth client, contact beehiiv Support" (developers.beehiiv.com/oauth2, read 2026-10-21). Ask beehiiv Support for a confidential OAuth client and give them:

• the redirect URL, which must match exactly. With the quickstart's default BOTSEON_PUBLIC_URL:

  http://127.0.0.1:3000/api/oauth/beehiiv-api/callback
  

  In general it is <BOTSEON_PUBLIC_URL>/api/oauth/beehiiv-api/callback (finding your redirect URL);

• the scopes in section 2.

beehiiv gives you a client id (its uid) and a client secret.

2. Scopes

The connector asks for the read half always, and the write half only when the member allows changes (F-PLUG-1: minimum scopes per capability, read and write requested separately):

• read: identify:read, publications:read, posts:read, subscriptions:read, segments:read
• write: posts:write, subscriptions:write

3. Enter the app

One command, with the client secret on standard input (see README.md):

printf %s "$CLIENT_SECRET" | botseon oauth-app set \
  --org <organisation id> --slug beehiiv-api \
  --client-id <the client id from beehiiv> \
  --auth-url https://app.beehiiv.com/oauth/authorize \
  --token-url https://app.beehiiv.com/oauth/token \
  --revoke-url https://app.beehiiv.com/oauth/revoke \
  --configured-by <your user id>

Set --revoke-url: with it, removing an account in Botseon also revokes the grant at beehiiv. The token exchange, refresh and revoke all send the client id and secret in a form body, which is what beehiiv documents; no provider profile is needed. botseon oauth-app show --org <id> --slug beehiiv-api prints the redirect URL and the client id, never the secret.

4. Check it

Install beehiiv (the connector) from the catalogue as a member, press Authenticate, sign in at beehiiv and allow access. The account should show Connected, and asking a bot "which beehiiv workspace are you connected to?" should answer with the workspace's name (beehiiv-api.identify_workspace).

Nightly, packages/connectors/src/beehiiv-api.live.test.ts checks the connector against the test workspace; its account and secrets are in docs/operations/connector-live-setup/beehiiv-api.md.

Never put the client secret, an access token or a beehiiv API key in a bot's description, a memory, or anywhere else a model reads as ordinary text.