Skip to main content
One Workchats company connects to one instance of your App through a standard OAuth 2.0 authorization-code flow. The resulting token belongs to the company (acting as your App’s bot user), not to the admin who clicked Connect, so it keeps working after that admin leaves.
Only company admins can approve. The consent screen names your App, lists the scopes, and lets the admin pick which groups and named channels your bot may join — including “switch company” if they admin more than one.
  • On approve: redirects to redirect_uri?code=<code>&state=<state>.
  • On deny: redirects to redirect_uri?error=access_denied&state=<state>.
redirect_uri must match what you registered with Octogle exactly. A code is single-use, expires in 10 minutes, and is bound to your client_id — a second redemption attempt gets invalid_grant and doesn’t revoke the token already issued, so retrying a timed-out exchange is safe.

​
2. Exchange the code for a token

Send client_id / client_secret in the body or as HTTP Basic credentials. grant_type must be authorization_code — Workchats tokens don’t expire, so there is no refresh_token grant; using one returns 400 unsupported_grant_type.
200
There’s no expires_in. Store access_token now — it’s shown once.

​
3. Send it as a bearer token

Only the Authorization header is accepted. A token in a query parameter (?token= or ?access_token=) gets 400 token_in_query — see Security.

​
Disconnecting

Always returns 200 {"ok": true}, including for an unknown or already revoked token. This disconnects: every token on the installation stops working immediately, but the bot stays in its groups and channels, so reconnecting later reuses the same bot and the same memberships. Nothing else removes the bot — only a company admin uninstalling your App in Workchats Settings, or Octogle disabling it, does that. No callback is sent for a revoke today. Until Phase 1b ships app.uninstalled, treat a 401 token_revoked response on any call as “disconnected” — see Callbacks & signature verification.

​
Who your bot can message

Your bot can DM active or onboarding people whose email is visible to it (subject to users:read.email’s release rule — see Concepts). DMs to guests ship in a later phase. Sending to a group or channel requires your bot to be an active member of it — the admin’s picks at install time, or later additions in Workchats Settings → Apps. Bot DMs are read-only for people: they see “this bot sends notifications here, replies aren’t delivered” instead of a composer. That’s enforced on the server, not just hidden in the client.

​
Managing the install later

In Workchats Settings → Apps, a company admin can add or remove your bot from groups and channels, toggle whether conversation posts push to phones, or uninstall your App entirely. None of this needs a call from you.