v4

OpenAPI 3.0.0MIT2026-07-311494532.1 MB

Integrations

Generate OAuth URL for a workspace/tenant connection

Generate an OAuth URL that creates a workspace or tenant-level channel connection (Slack workspace install, MS Teams admin consent, or Webex integration authorization). The generated URL expires after 5 minutes.

post/v1/integrations/channel-connections/oauth

Headers

idempotency-keystring

A header for idempotency purposes

Request body

subscriberIdstring

The subscriber ID to associate with the channel connection. For Slack: optional for workspace connections (required only for incoming-webhook scope). For Webex: optional for workspace connections. For MS Teams: optional. Admin consent is tenant-wide.

integrationIdentifierstring required

Integration identifier

connectionIdentifierstring

Identifier of the channel connection that will be created. Generated automatically if not provided.

contextobject

contextHashstring

HMAC-SHA256 of the canonicalized context, signed with the tenant environment secret key (the same "Inbox with context" signing scheme). Required when the integration has HMAC validation enabled and the session did not already HMAC-verify the context. Establishes that the context/tenant binding was minted by an authenticated backend rather than forged in the browser.

scopestring[]

Slack only: OAuth scopes to request during authorization. If not specified, default scopes will be used: chat:write, chat:write.public, channels:read, groups:read, users:read, users:read.email. Webex: OAuth scopes to request during authorization. Defaults to: spark:messages_write, spark:rooms_read, spark:people_read, spark:memberships_read, spark:kms. MS Teams: ignored — uses admin consent with pre-configured Azure AD permissions.

connectionMode'subscriber' | 'shared'

Connection mode that determines how the channel connection is scoped. "subscriber" (default) associates the connection with a specific subscriber. "shared" associates the connection with a context instead of a subscriber.

autoLinkUserboolean

When true (default when connectionMode is "subscriber"), after the workspace/tenant connection is created the OAuth flow also links the subscriber who clicked "Connect" as a personal endpoint. For Slack, uses the authed_user.id returned by oauth.v2.access — no extra redirect. For Webex, uses the authenticated Webex person returned by people/me — no extra redirect. For MS Teams, triggers a second OAuth redirect for delegated user-identity consent. Set to false to only create the workspace connection without linking the individual user.

Example request

{
  "subscriberId": "subscriber-123",
  "connectionIdentifier": "slack-connection-abc123",
  "contextHash": "a1b2c3d4e5f6...",
  "scope": [
    "chat:write",
    "chat:write.public",
    "channels:read"
  ],
  "connectionMode": "shared",
  "autoLinkUser": true
}

Response

Created

urlstring required

The OAuth authorization URL for the chat provider. For Slack: https://slack.com/oauth/v2/authorize?... For MS Teams: https://login.microsoftonline.com/.../adminconsent?... This URL should be presented to the user to authorize the integration. Expires after 5 minutes.

Example response

{
  "url": "https://slack.com/oauth/v2/authorize?state=..."
}