Skip to main content
POST
/
v1
/
integrations
/
channel-connections
/
oauth
PHP
declare(strict_types=1);

require 'vendor/autoload.php';

use novu;
use novu\Models\Components;

$sdk = novu\Novu::builder()
    ->setSecurity(
        'YOUR_SECRET_KEY_HERE'
    )
    ->build();

$generateConnectOauthUrlRequestDto = new Components\GenerateConnectOauthUrlRequestDto(
    subscriberId: 'subscriber-123',
    integrationIdentifier: '<value>',
    connectionIdentifier: 'slack-connection-abc123',
    context: [
        'key' => 'org-acme',
    ],
    scope: [
        'chat:write',
        'chat:write.public',
        'channels:read',
    ],
    connectionMode: Components\GenerateConnectOauthUrlRequestDtoConnectionMode::Shared,
    autoLinkUser: true,
);

$response = $sdk->integrations->generateConnectOAuthUrl(
    generateConnectOauthUrlRequestDto: $generateConnectOauthUrlRequestDto
);

if ($response->generateChatOAuthUrlResponseDto !== null) {
    // handle response
}
{
  "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 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.

Example:

"subscriber-123"

​
connectionIdentifier
string

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

Example:

"slack-connection-abc123"

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

Example:
[
  "chat:write",
  "chat:write.public",
  "channels:read"
]
​
connectionMode
enum<string>

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.

Available options:
subscriber,
shared
Example:

"shared"

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

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