Generate OAuth URL to link a subscriber user identity

POST

integrations

channel-endpoints

oauth

TypeScript

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: "YOUR_SECRET_KEY_HERE",
});

async function run() {
  const result = await novu.integrations.generateLinkUserOAuthUrl({
    subscriberId: "subscriber-123",
    integrationIdentifier: "<value>",
    connectionIdentifier: "slack-connection-abc123",
    context: {
      "key": "org-acme",
    },
    userScope: [
      "identity.basic",
    ],
  });

  console.log(result);
}

run();

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "YOUR_SECRET_KEY_HERE");

var res = await sdk.Integrations.GenerateLinkUserOAuthUrlAsync(generateLinkUserOauthUrlRequestDto: new GenerateLinkUserOauthUrlRequestDto() {
    SubscriberId = "subscriber-123",
    IntegrationIdentifier = "<value>",
    ConnectionIdentifier = "slack-connection-abc123",
    Context = new Dictionary<string, GenerateLinkUserOauthUrlRequestDtoContext>() {
        { "key", GenerateLinkUserOauthUrlRequestDtoContext.CreateStr(
            "org-acme"
        ) },
    },
    UserScope = new List<string>() {
        "identity.basic",
    },
});

// handle response

declare(strict_types=1);

require 'vendor/autoload.php';

use novu;
use novu\Models\Components;

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

$generateLinkUserOauthUrlRequestDto = new Components\GenerateLinkUserOauthUrlRequestDto(
    subscriberId: 'subscriber-123',
    integrationIdentifier: '<value>',
    connectionIdentifier: 'slack-connection-abc123',
    context: [
        'key' => 'org-acme',
    ],
    userScope: [
        'identity.basic',
    ],
);

$response = $sdk->integrations->generateLinkUserOAuthUrl(
    generateLinkUserOauthUrlRequestDto: $generateLinkUserOauthUrlRequestDto
);

if ($response->generateChatOAuthUrlResponseDto !== null) {
    // handle response
}

from novu_py import Novu


with Novu(
    secret_key="YOUR_SECRET_KEY_HERE",
) as novu:

    res = novu.integrations.generate_link_user_o_auth_url(generate_link_user_oauth_url_request_dto={
        "subscriber_id": "subscriber-123",
        "integration_identifier": "<value>",
        "connection_identifier": "slack-connection-abc123",
        "context": {
            "key": "org-acme",
        },
        "user_scope": [
            "identity.basic",
        ],
    })

    # Handle response
    print(res)

package main

import(
	"context"
	"github.com/novuhq/novu-go/v3"
	"github.com/novuhq/novu-go/v3/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := v3.New(
        v3.WithSecurity("YOUR_SECRET_KEY_HERE"),
    )

    res, err := s.Integrations.GenerateLinkUserOAuthURL(ctx, components.GenerateLinkUserOauthURLRequestDto{
        SubscriberID: "subscriber-123",
        IntegrationIdentifier: "<value>",
        ConnectionIdentifier: v3.Pointer("slack-connection-abc123"),
        Context: map[string]components.GenerateLinkUserOauthURLRequestDtoContext{
            "key": components.CreateGenerateLinkUserOauthURLRequestDtoContextStr(
                "org-acme",
            ),
        },
        UserScope: []string{
            "identity.basic",
        },
    }, nil)
    if err != nil {
        log.Fatal(err)
    }
    if res.GenerateChatOAuthURLResponseDto != nil {
        // handle response
    }
}

curl --request POST \
  --url https://api.novu.co/v1/integrations/channel-endpoints/oauth \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscriberId": "subscriber-123",
  "integrationIdentifier": "<string>",
  "connectionIdentifier": "slack-connection-abc123",
  "context": {},
  "userScope": [
    "identity.basic"
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    subscriberId: 'subscriber-123',
    integrationIdentifier: '<string>',
    connectionIdentifier: 'slack-connection-abc123',
    context: {},
    userScope: ['identity.basic']
  })
};

fetch('https://api.novu.co/v1/integrations/channel-endpoints/oauth', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://api.novu.co/v1/integrations/channel-endpoints/oauth")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"subscriberId\": \"subscriber-123\",\n  \"integrationIdentifier\": \"<string>\",\n  \"connectionIdentifier\": \"slack-connection-abc123\",\n  \"context\": {},\n  \"userScope\": [\n    \"identity.basic\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.novu.co/v1/integrations/channel-endpoints/oauth")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"subscriberId\": \"subscriber-123\",\n  \"integrationIdentifier\": \"<string>\",\n  \"connectionIdentifier\": \"slack-connection-abc123\",\n  \"context\": {},\n  \"userScope\": [\n    \"identity.basic\"\n  ]\n}"

response = http.request(request)
puts response.read_body

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

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "errors": {
    "fieldName1": {
      "messages": [
        "Field is required",
        "Must be a valid email address"
      ],
      "value": "invalidEmail"
    },
    "fieldName2": {
      "messages": [
        "Must be at least 18 years old"
      ],
      "value": 17
    },
    "fieldName3": {
      "messages": [
        "Must be a boolean value"
      ],
      "value": true
    },
    "fieldName4": {
      "messages": [
        "Must be a valid object"
      ],
      "value": {
        "key": "value"
      }
    },
    "fieldName5": {
      "messages": [
        "Field is missing"
      ],
      "value": null
    },
    "fieldName6": {
      "messages": [
        "Undefined value"
      ]
    }
  },
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"API rate limit exceeded"

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"Please wait some time, then try again."

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

subscriberId

string

required

The subscriber ID to link to their chat identity. Required — this operation always binds a specific subscriber to a user identity in the chat provider.

Example:

"subscriber-123"

integrationIdentifier

string

required

Integration identifier

connectionIdentifier

string

Identifier of the existing channel connection to associate this user endpoint with. Generated automatically if not provided.

Example:

"slack-connection-abc123"

context

object

Show child attributes

userScope

string[]

Slack only: User-level OAuth scopes for "Sign in with Slack". Defaults to: identity.basic. MS Teams: ignored — uses delegated OpenID scopes (openid, profile, User.Read).

Example:

["identity.basic"]

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

Issue a URL to link a subscriber chat identity

Generate chat OAuth URL

⌘I

TypeScript

import { Novu } from "@novu/api";

const novu = new Novu({
  secretKey: "YOUR_SECRET_KEY_HERE",
});

async function run() {
  const result = await novu.integrations.generateLinkUserOAuthUrl({
    subscriberId: "subscriber-123",
    integrationIdentifier: "<value>",
    connectionIdentifier: "slack-connection-abc123",
    context: {
      "key": "org-acme",
    },
    userScope: [
      "identity.basic",
    ],
  });

  console.log(result);
}

run();

using Novu;
using Novu.Models.Components;
using System.Collections.Generic;

var sdk = new NovuSDK(secretKey: "YOUR_SECRET_KEY_HERE");

var res = await sdk.Integrations.GenerateLinkUserOAuthUrlAsync(generateLinkUserOauthUrlRequestDto: new GenerateLinkUserOauthUrlRequestDto() {
    SubscriberId = "subscriber-123",
    IntegrationIdentifier = "<value>",
    ConnectionIdentifier = "slack-connection-abc123",
    Context = new Dictionary<string, GenerateLinkUserOauthUrlRequestDtoContext>() {
        { "key", GenerateLinkUserOauthUrlRequestDtoContext.CreateStr(
            "org-acme"
        ) },
    },
    UserScope = new List<string>() {
        "identity.basic",
    },
});

// handle response

declare(strict_types=1);

require 'vendor/autoload.php';

use novu;
use novu\Models\Components;

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

$generateLinkUserOauthUrlRequestDto = new Components\GenerateLinkUserOauthUrlRequestDto(
    subscriberId: 'subscriber-123',
    integrationIdentifier: '<value>',
    connectionIdentifier: 'slack-connection-abc123',
    context: [
        'key' => 'org-acme',
    ],
    userScope: [
        'identity.basic',
    ],
);

$response = $sdk->integrations->generateLinkUserOAuthUrl(
    generateLinkUserOauthUrlRequestDto: $generateLinkUserOauthUrlRequestDto
);

if ($response->generateChatOAuthUrlResponseDto !== null) {
    // handle response
}

from novu_py import Novu


with Novu(
    secret_key="YOUR_SECRET_KEY_HERE",
) as novu:

    res = novu.integrations.generate_link_user_o_auth_url(generate_link_user_oauth_url_request_dto={
        "subscriber_id": "subscriber-123",
        "integration_identifier": "<value>",
        "connection_identifier": "slack-connection-abc123",
        "context": {
            "key": "org-acme",
        },
        "user_scope": [
            "identity.basic",
        ],
    })

    # Handle response
    print(res)

package main

import(
	"context"
	"github.com/novuhq/novu-go/v3"
	"github.com/novuhq/novu-go/v3/models/components"
	"log"
)

func main() {
    ctx := context.Background()

    s := v3.New(
        v3.WithSecurity("YOUR_SECRET_KEY_HERE"),
    )

    res, err := s.Integrations.GenerateLinkUserOAuthURL(ctx, components.GenerateLinkUserOauthURLRequestDto{
        SubscriberID: "subscriber-123",
        IntegrationIdentifier: "<value>",
        ConnectionIdentifier: v3.Pointer("slack-connection-abc123"),
        Context: map[string]components.GenerateLinkUserOauthURLRequestDtoContext{
            "key": components.CreateGenerateLinkUserOauthURLRequestDtoContextStr(
                "org-acme",
            ),
        },
        UserScope: []string{
            "identity.basic",
        },
    }, nil)
    if err != nil {
        log.Fatal(err)
    }
    if res.GenerateChatOAuthURLResponseDto != nil {
        // handle response
    }
}

curl --request POST \
  --url https://api.novu.co/v1/integrations/channel-endpoints/oauth \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "subscriberId": "subscriber-123",
  "integrationIdentifier": "<string>",
  "connectionIdentifier": "slack-connection-abc123",
  "context": {},
  "userScope": [
    "identity.basic"
  ]
}
'

const options = {
  method: 'POST',
  headers: {Authorization: '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    subscriberId: 'subscriber-123',
    integrationIdentifier: '<string>',
    connectionIdentifier: 'slack-connection-abc123',
    context: {},
    userScope: ['identity.basic']
  })
};

fetch('https://api.novu.co/v1/integrations/channel-endpoints/oauth', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

HttpResponse<String> response = Unirest.post("https://api.novu.co/v1/integrations/channel-endpoints/oauth")
  .header("Authorization", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"subscriberId\": \"subscriber-123\",\n  \"integrationIdentifier\": \"<string>\",\n  \"connectionIdentifier\": \"slack-connection-abc123\",\n  \"context\": {},\n  \"userScope\": [\n    \"identity.basic\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.novu.co/v1/integrations/channel-endpoints/oauth")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"subscriberId\": \"subscriber-123\",\n  \"integrationIdentifier\": \"<string>\",\n  \"connectionIdentifier\": \"slack-connection-abc123\",\n  \"context\": {},\n  \"userScope\": [\n    \"identity.basic\"\n  ]\n}"

response = http.request(request)
puts response.read_body

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

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "errors": {
    "fieldName1": {
      "messages": [
        "Field is required",
        "Must be a valid email address"
      ],
      "value": "invalidEmail"
    },
    "fieldName2": {
      "messages": [
        "Must be at least 18 years old"
      ],
      "value": 17
    },
    "fieldName3": {
      "messages": [
        "Must be a boolean value"
      ],
      "value": true
    },
    "fieldName4": {
      "messages": [
        "Must be a valid object"
      ],
      "value": {
        "key": "value"
      }
    },
    "fieldName5": {
      "messages": [
        "Field is missing"
      ],
      "value": null
    },
    "fieldName6": {
      "messages": [
        "Undefined value"
      ]
    }
  },
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"API rate limit exceeded"

{
  "statusCode": 404,
  "timestamp": "2024-12-12T13:00:00Z",
  "path": "/api/v1/resource",
  "message": "xx xx xx ",
  "ctx": {
    "workflowId": "some_wf_id",
    "stepId": "some_wf_id"
  },
  "errorId": "abc123"
}

"Please wait some time, then try again."

Getting Started

Events

Subscribers

Inbox

Topics

Notifications

Workflows

Translations

Contexts

Environments

Environment Variables

Messages

Integrations

Channel Connections

Channel Endpoints

Activity

Layouts

Contexts

Environments

Activity

Layouts

Subscribers

Topics

Translations

Workflows

Channel Connections

Channel Endpoints

Domains

Environment Variables

Events

Integrations

Messages

Notifications

Generate OAuth URL to link a subscriber user identity

Authorizations

Headers

Body

Response