Search2oSearch2oAgent server for the enterprise
Docs / Chat integrations

Connecting a person

The bot acts as a person, so the bot needs a token for that person. The person creates the token. A password never reaches the bot.

There are two ways to create the token. Both produce the same kind of token.

Pasting a token

The person signs in to the UI and creates an integration token from their profile. The UI shows the token once. The person copies the token into the bot, usually with a slash command in a private message.

This needs nothing from the bot beyond somewhere to store the token, and it suits a small team. It does not suit a large one: a token pasted into a public chat message stays in that workspace's history.

The connect flow

The bot sends the person a button that opens a page on the agent server. The person signs in if not signed in already, approves the request, and returns to the chat application. The bot collects the token by itself; nothing is copied by hand.

  1. The bot calls startConnect with a name to display, such as the name of the chat workspace. The call returns an identifier, a secret, a short code and an address.
  2. The bot posts a button pointing at that address, and shows the short code beside the button.
  3. The person opens the page. The page shows what is asking for access and the same short code.
  4. The person compares the two codes and approves. A token is created for that person.
  5. The bot calls getConnectToken with the identifier and the secret, no more often than the poll interval, until the status is approved, denied or expired. The token comes back once, with the approved status.
$ curl -s -X POST http://127.0.0.1:9020/api/auth/startConnect \
    -H "Content-Type: application/json" \
    -d '{"clientName": "Slack - Acme workspace"}'
{"success": true, "connectId": "…", "connectSecret": "…",
 "connectUrl": "…", "userCode": "ZUEZFA",
 "expiresIn": 600, "pollIntervalSeconds": 5}

A request stays open for ten minutes. startConnect, getConnectRequest and getConnectToken need no token of their own. Every other call the bot makes carries the person's token; see Authentication.

The short code

The short code is what protects the person. A link on its own is not enough for a request to be approved, because a request started by somebody else shows a code the person has never seen. Tell people to compare the two codes. A bot must never show a code that did not come from startConnect.

The secret from the first call belongs to the bot. Never show it to the person, and never put it in a link.

Where the approval page lives

The address comes from the connect page URL setting on the agent server. Leave it empty when the agent server serves the UI, and the address follows wherever the UI is served. Set a path for a UI of your own, or a full address for a UI hosted somewhere else; the UI is a set of static pages that can be hosted anywhere. When the agent server serves no UI and the setting is empty, startConnect refuses, because there is nowhere to approve the request.

The agent server adds the request's identifier to that address as the query parameter c, so a page that reads the parameter works whichever way the UI is built. The bot receives a full address, or a path when the UI is served by the agent server. Use a full address as it is; join a path to the agent server's address.