Generate OAuth URL for a workspace/tenant connection

Generate an OAuth URL that creates a workspace or tenant-level channel connection (Slack workspace install or MS Teams admin consent). 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 associate with the channel connection. For Slack: optional for workspace connections (required only for incoming-webhook scope). For MS Teams: optional. Admin consent is tenant-wide.

integrationIdentifierRequiredstring

Integration identifier

connectionIdentifierstring

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

contextobject

scopearray<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. MS Teams: ignored — uses admin consent with pre-configured Azure AD permissions.

connectionModestring

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.

Value in: "subscriber" | "shared"

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 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.

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/channel-connections/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"
    ],
    "connectionMode": "shared",
    "autoLinkUser": true
  }'

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

Generate OAuth URL for a workspace/tenant connection

Authorization

Request Body

Header Parameters

Response Body

On this page