Zendesk connector setup

This page is the setup half — creating the OAuth client Zendesk needs in your own Zendesk Admin Center 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 Zendesk.

1. Create the OAuth client on your Zendesk subdomain

1. In your Zendesk Admin Center, open Apps and integrations → APIs → OAuth clients and add a new OAuth client — this is your own client, on your own subdomain, not Botseon's.

2. Under Redirect URLs, 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/zendesk/callback
   

3. Save. Admin Center shows you the client's Unique identifier and a Secret — copy both now.

2. Scopes

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

• read — read tickets, users and organisations; no writes.
• write — create and update tickets, users and organisations.

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 zendesk \
  --client-id <the client ID from step 1> \
  --auth-url https://<your Zendesk subdomain>.zendesk.com/oauth/authorizations/new \
  --token-url https://<your Zendesk subdomain>.zendesk.com/oauth/tokens \
  --configured-by <your user id>

Both URLs are read from Zendesk's own current documentation (Using OAuth to authenticate Zendesk API requests in a web app), not invented here; the client's own subdomain replaces <your Zendesk subdomain> in both.

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 zendesk 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.