---
title: "Generate OAuth URL for a workspace/tenant connection"
method: POST
path: "/v1/integrations/channel-connections/oauth"
tags: ["Integrations"]
---

# Generate OAuth URL for a workspace/tenant connection

`POST /v1/integrations/channel-connections/oauth`

## Request

- Base URL: `https://api.notifly.io`
- URL: `https://api.notifly.io/v1/integrations/channel-connections/oauth`
- Auth: API key in header `Authorization`

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.

## Request body

- GenerateConnectOauthUrlRequestDto
  - `subscriberId` string: 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.
  - `integrationIdentifier` string, required: Integration identifier
  - `connectionIdentifier` string: Identifier of the channel connection that will be created. Generated automatically if not provided.
  - `context` object
  - `contextHash` string: 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.
  - `scope` string[]: **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.
  - `autoLinkUser` boolean: 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.

## Response `201`

Created

- object
  - `data` GenerateChatOAuthUrlResponseDto
    - `url` string, 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.

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `405`: Method Not Allowed
- `409`: Conflict
- `413`: Payload Too Large
- `414`: URI Too Long
- `415`: Unsupported Media Type
- `422`: Unprocessable Entity
- `429`: The client has sent too many requests in a given amount of time.
- `500`: Internal Server Error
- `503`: The server is currently unable to handle the request due to a temporary overload or scheduled maintenance, which will likely be alleviated after some delay.

---

[API](https://skmtc.dev/notifly/apis/notifly-api.md) · [All operations](https://skmtc.dev/notifly/apis/notifly-api/llms.txt) · [OpenAPI document](https://skmtc.dev/notifly/apis/notifly-api/revisions/af909b9e1e57?raw)