X connector setup

This page is the setup half — creating the OAuth app X needs in its own developer portal and getting its client id and secret into this deployment. Authorising a connection afterwards is the Authenticate control on the plugin sheet, which is what actually sends you to X.

1. Create the OAuth app in the X developer portal

1. Open the X developer portal and create a new app with OAuth 2.0 enabled — this is your own app, not Botseon's.

2. Under User authentication settings → Callback URI / Redirect URL, add the redirect URL from docs/connectors/README.md — with the quickstart's default BOTSEON_PUBLIC_URL, that is:

   http://127.0.0.1:3000/api/oauth/x/callback
   

3. Save. The portal shows you a Client ID and a Client Secret — copy both now.

2. Scopes

Request the narrowest set that covers the tools this connector exposes (F-PLUG-1: minimum scopes per capability, read and write requested separately):

• tweet.read — read posts and their metadata; no writes.
• users.read — read profile information for accounts referenced in a post.
• offline.access — issue a refresh token, so the connection survives past the access token's own short lifetime.

3. Enter the app

One command, with the client secret on standard input — there is no flag that takes it and no environment variable that holds it (see docs/connectors/README.md):

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

Both URLs use the x.com domain, matching this connector's own resource API base (https://api.x.com/2 in packages/connectors/src/x.ts) rather than the older twitter.com domain, so the app-setup step and the connector's own calls agree on one domain. X's cited documentation (OAuth 2.0 Authorization Code Flow with PKCE) was not reachable to independently confirm the exact pair — if your organisation's app registration needs the twitter.com authorize host instead, use the value X's current portal shows you.

It stores the secret encrypted and prints the redirect URL from step 1 back, so you can check the two match. botseon oauth-app show --org <organisation id> --slug x says whether an app is configured and under which client id; nothing prints the secret back.

Never put either value in a bot's description, a memory, or anywhere else a model reads as ordinary text.