Skip to main content
POST
/
v1
/
integrations
/
chat
/
oauth
Generate chat OAuth URL
curl --request POST \
  --url https://api.novu.co/v1/integrations/chat/oauth \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "integrationIdentifier": "<string>",
  "subscriberId": "subscriber-123",
  "connectionIdentifier": "slack-connection-abc123",
  "context": {},
  "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=..."
}

Authorizations

​
Authorization
string
header
required

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

Headers

​
idempotency-key
string

A header for idempotency purposes

Body

application/json
​
integrationIdentifier
string
required

Integration identifier

​
subscriberId
string

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.

Example:

"subscriber-123"

​
connectionIdentifier
string

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

Example:

"slack-connection-abc123"

​
context
object
​
scope
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.

Example:
[
  "chat:write",
  "chat:write.public",
  "channels:read",
  "groups:read",
  "users:read",
  "users:read.email",
  "incoming-webhook"
]
​
userScope
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.

Example:
["identity.basic"]
​
mode
enum<string>

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.

Available options:
connect,
link_user
Example:

"link_user"

​
connectionMode
enum<string>

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.

Available options:
subscriber,
shared
Example:

"shared"

​
autoLinkUser
boolean

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.

Example:

true

Response

Created

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

Example:

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