Generate chat OAuth URL

Deprecated — use POST /integrations/channel-connections/oauth (connect) or POST /integrations/channel-endpoints/oauth (link_user) instead. Generate an OAuth URL for chat integrations like Slack and MS Teams. This URL allows subscribers to authorize the integration, enabling the system to send messages through their chat workspace. The generated URL expires after 5 minutes.

Authorization

Authorization<token>

API key authentication. Allowed headers-- "Authorization: ApiKey <novu_secret_key>".

In: header

Request Body

application/jsonRequired

subscriberIdstring

The subscriber ID to link the channel connection to. For Slack: Required for incoming webhook endpoints, optional for workspace connections. For MS Teams: Optional. Admin consent is tenant-wide and can be associated with a subscriber for organizational purposes.

integrationIdentifierRequiredstring

Integration identifier

connectionIdentifierstring

Identifier of the channel connection that will be created. It is generated automatically if not provided.

contextobject

scopearray<string>

Slack only: OAuth scopes to request during authorization. These define the permissions your Slack integration will have. If not specified, default scopes will be used: chat:write, chat:write.public, channels:read, groups:read, users:read, users:read.email. MS Teams: This parameter is ignored. MS Teams uses admin consent with pre-configured permissions in Azure AD. Note: The generated OAuth URL expires after 5 minutes.

userScopearray<string>

Slack only, link_user mode: User-level OAuth scopes to request during authorization. Used when mode is "link_user" to identify the Slack user via "Sign in with Slack". If not specified, defaults to: identity.basic.

modestring

OAuth flow mode. Use "connect" (default) to create a workspace channel connection, or "link_user" to identify the subscriber's Slack user ID without creating a connection.

Value in: "connect" | "link_user"

connectionModestring

Connection mode that determines how the channel connection is scoped. Use "subscriber" (default) to associate the connection with a specific subscriber. Use "shared" to associate the connection with a context instead of a subscriber — subscriberId will not be stored on the connection.

Value in: "subscriber" | "shared"

autoLinkUserboolean

When true, after the workspace/tenant connection is created the OAuth flow also links the subscriber who clicked "Connect" as a personal endpoint. For Slack, this uses the authed_user.id already returned by oauth.v2.access — no extra redirect. For MS Teams, this triggers a second OAuth redirect for delegated user-identity consent. Defaults to false when omitted; the SlackConnectButton and MsTeamsConnectButton SDK components default this to true.

Header Parameters

idempotency-keystring

A header for idempotency purposes

Response Body

Created

urlRequiredstring

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.

export interface Response {
  /**
   * 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.
   */
  url: string;
}

curl -X POST "https://api.novu.co/v1/integrations/chat/oauth" \
  -H "idempotency-key: string" \
  -H "Authorization: <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "subscriberId": "subscriber-123",
    "integrationIdentifier": "string",
    "connectionIdentifier": "slack-connection-abc123",
    "context": {
      "property1": "org-acme",
      "property2": "org-acme"
    },
    "scope": [
      "chat:write",
      "chat:write.public",
      "channels:read",
      "groups:read",
      "users:read",
      "users:read.email",
      "incoming-webhook"
    ],
    "userScope": [
      "identity.basic"
    ],
    "mode": "link_user",
    "connectionMode": "shared",
    "autoLinkUser": true
  }'

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

Generate chat OAuth URL

Authorization

Request Body

Header Parameters

Response Body

On this page