Skip to content

Commit 31eec82

Browse files
scopsycursoragentgreptile-apps[bot]
authored
docs(docs): add authentication page and REST API overview fixes DOC-375 (#11675)
Co-authored-by: Cursor Agent <cursoragent@cursor.com> Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
1 parent 6d2b023 commit 31eec82

3 files changed

Lines changed: 203 additions & 30 deletions

File tree

‎docs/api-reference.mdx‎

Lines changed: 73 additions & 29 deletions
Original file line numberDiff line numberDiff line change
@@ -1,47 +1,91 @@
11
---
22
title: 'Overview'
3-
description: "Complete Novu API reference covering authentication, endpoints, rate limits, and server-side integration for notifications."
3+
description: 'High-level overview of the Novu REST API, available resources, and links to OpenAPI, Postman, SDKs, and getting started guides.'
44
---
55

6+
The Novu REST API lets you manage subscribers, trigger workflows, configure integrations, and operate your notification infrastructure from your backend. Use it directly with HTTP requests, or through one of our [server-side SDKs](/platform/sdks#server-side-sdks).
7+
68
<Note>
7-
It's important to note that our API and backend SDK are intended for use exclusively in
8-
server-side applications. **Attempting to use them in a client-side application will result in
9-
Cross-Origin Resource Sharing (CORS) errors.** This restriction ensures the security and integrity
10-
of our services.
9+
The REST API and server-side SDKs are intended for server-side applications only. Using them in client-side code causes Cross-Origin Resource Sharing (CORS) errors and exposes your secret key.
1110
</Note>
1211

13-
## Authentication
12+
## Base URL
1413

15-
Authentication for the Novu API involves the use of an API Key, which is a secure credential that is tied to your Novu account. This key should be included in the header of the request in the Authorization field as a string prefixed with 'ApiKey '.
14+
| Region | Base URL |
15+
| --- | --- |
16+
| **US (default)** | `https://api.novu.co/v1` |
17+
| **EU** | `https://eu.api.novu.co/v1` |
1618

17-
```bash
18-
--header 'Authorization: ApiKey <NOVU_SECRET_KEY>'
19-
```
19+
All endpoints in this reference use the US base URL unless noted otherwise. See [Authentication](/api-reference/authentication) for regional WebSocket hostnames and credential setup.
2020

21-
For example, when using Novu in a Node.js application, the Novu package should be imported and initialized with the API key, as shown in this snippet:
21+
## API capabilities
2222

23-
```javascript
24-
import { Novu } from '@novu/api';
25-
const novu = new Novu({
26-
secretKey: "NOVU_SECRET_KEY",
27-
});
28-
```
23+
The REST API is organized around the core resources you use to build and operate notifications:
2924

30-
Replace `<NOVU_SECRET_KEY>` with your actual API Key, available in the API Key section of the Novu Dashboard.
25+
<Columns cols={2}>
26+
<Card title="Events" icon="zap" href="/api-reference/events/trigger-event">
27+
Trigger, bulk trigger, broadcast, and cancel workflow executions.
28+
</Card>
29+
<Card title="Subscribers" icon="users" href="/api-reference/subscribers/create-a-subscriber">
30+
Create, update, and manage notification recipients and their preferences.
31+
</Card>
32+
<Card title="Inbox" icon="inbox" href="/api-reference/subscribers/retrieve-subscriber-notifications">
33+
Read, mark, archive, snooze, and manage in-app notifications.
34+
</Card>
35+
<Card title="Topics" icon="hash" href="/api-reference/topics/create-a-topic">
36+
Group subscribers and send notifications to topic audiences.
37+
</Card>
38+
<Card title="Workflows" icon="git-branch" href="/api-reference/workflows/create-a-workflow">
39+
Create, sync, and manage notification workflow definitions.
40+
</Card>
41+
<Card title="Integrations" icon="plug" href="/api-reference/integrations/create-an-integration">
42+
Configure channel providers for email, SMS, push, and chat delivery.
43+
</Card>
44+
<Card title="Environments" icon="server" href="/api-reference/environments/list-all-environments">
45+
Manage environments and publish resources between them.
46+
</Card>
47+
<Card title="Messages" icon="message-square" href="/api-reference/messages/list-all-messages">
48+
List and delete sent messages across channels.
49+
</Card>
50+
</Columns>
3151

32-
<Warning>
33-
It is advised not to hardcode your credentials in a file in production environments. Use
34-
environment variables instead.
35-
</Warning>
52+
Browse the sidebar for the full endpoint reference, including translations, contexts, layouts, channel connections, and activity tracking.
3653

37-
## API Endpoints
54+
## Developer resources
3855

39-
Novu provides a multitude of API endpoints that enable a variety of functionalities. the base URL for the Novu API is `https://api.novu.co/v1`.
56+
Use these resources to explore, test, and integrate with the API:
4057

41-
<Note>
42-
We offer two API options: the US API and the EU API. By default, our API documentation refers to the US API, which can be accessed at: https://api.novu.co/v1.
58+
<Columns cols={2}>
59+
<Card title="OpenAPI specification" icon="file-json" href="https://api.novu.co/openapi.json">
60+
Machine-readable API schema for code generation, validation, and tooling.
61+
</Card>
62+
<Card title="Postman collection" icon="send" href="https://github.com/novuhq/novu-postman/blob/main/postman/novu_api_postman_collection.json">
63+
Pre-built requests to test endpoints in Postman or compatible tools.
64+
</Card>
65+
<Card title="Server-side SDKs" icon="code" href="/platform/sdks#server-side-sdks">
66+
Official SDKs for TypeScript, Python, Go, PHP, .NET, and Java.
67+
</Card>
68+
<Card title="Authentication" icon="key" href="/api-reference/authentication">
69+
Set up API keys, environment credentials, and security best practices.
70+
</Card>
71+
</Columns>
4372

44-
If you require the EU version, you can access it here: https://eu.api.novu.co/v1.
45-
</Note>
73+
### Import the Postman collection
74+
75+
1. Clone or download the [novu-postman](https://github.com/novuhq/novu-postman) repository.
76+
2. Import `postman/novu_api_postman_collection.json` into Postman.
77+
3. Set the `secretKey` collection variable to your environment's secret key from the [API Keys](https://dashboard.novu.co/api-keys) page.
78+
79+
## Getting started
4680

47-
For instance, to get tenant information, the endpoint to use would include the tenant's identifier and look like this `https://api.novu.co/v1/tenants/{identifier}`.
81+
<Steps>
82+
<Step title="Get your API key">
83+
Copy your environment's secret key from the [Novu Dashboard](https://dashboard.novu.co/api-keys). See [Authentication](/api-reference/authentication) for details on credential types and security.
84+
</Step>
85+
<Step title="Make your first request">
86+
Trigger a workflow or create a subscriber using the REST API or an SDK. Start with [Trigger event](/api-reference/events/trigger-event) or [Create a subscriber](/api-reference/subscribers/create-a-subscriber).
87+
</Step>
88+
<Step title="Review API policies">
89+
Understand [Rate limiting](/api-reference/rate-limiting), [Idempotency](/api-reference/idempotency), and [Payload limits](/api-reference/payload-limits) before building production integrations.
90+
</Step>
91+
</Steps>

‎docs/api-reference/authentication.mdx‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,123 @@
1+
---
2+
title: 'Authentication'
3+
description: 'Authenticate REST API requests with your Novu secret key, manage environment credentials, and follow security best practices.'
4+
---
5+
6+
The Novu REST API uses API key authentication. Every server-side request must include your environment's secret key in the `Authorization` header.
7+
8+
<Note>
9+
The REST API and server-side SDKs are intended for server-side applications only. Using them in client-side code causes Cross-Origin Resource Sharing (CORS) errors and exposes your secret key.
10+
</Note>
11+
12+
## API key authentication
13+
14+
Include your secret key in the `Authorization` header, prefixed with `ApiKey`:
15+
16+
```bash
17+
--header 'Authorization: ApiKey <NOVU_SECRET_KEY>'
18+
```
19+
20+
Example request:
21+
22+
```bash
23+
curl -X GET https://api.novu.co/v1/subscribers \
24+
--header 'Authorization: ApiKey <NOVU_SECRET_KEY>'
25+
```
26+
27+
### Initialize the SDK
28+
29+
When using a server-side SDK, pass your secret key during initialization:
30+
31+
```javascript
32+
import { Novu } from '@novu/api';
33+
34+
const novu = new Novu({
35+
secretKey: process.env.NOVU_SECRET_KEY,
36+
});
37+
```
38+
39+
<Warning>
40+
Do not hardcode credentials in source code. Store your secret key in environment variables or a secrets manager.
41+
</Warning>
42+
43+
## Credential types
44+
45+
Each Novu environment has two credentials. Use the right one for the context:
46+
47+
| Credential | Visibility | Used for |
48+
| --- | --- | --- |
49+
| **Secret key** | Private | Authenticating REST API and server-side SDK requests |
50+
| **Application identifier** | Public | Initializing the [`<Inbox />`](/platform/inbox) component and client-side SDKs |
51+
52+
The secret key grants full administrative access to your environment. Never expose it in frontend code, public repositories, or browser network requests.
53+
54+
The application identifier is safe to use in client-side code. It identifies your application within Novu but does not authorize API requests on its own.
55+
56+
## Find your API keys
57+
58+
1. Log in to the [Novu Dashboard](https://dashboard.novu.co).
59+
2. Go to **Developer** → **API Keys**.
60+
3. Select the environment you want to use (Development, Production, or a custom environment).
61+
62+
Each environment has its own secret key and application identifier. Use the credentials that match the environment you are targeting.
63+
64+
![API Keys](/images/developer-tools/api-keys.png)
65+
66+
<Card title="API keys" icon="key" href="/platform/developer/api-keys">
67+
Learn more about application identifiers, secret keys, and API hostnames.
68+
</Card>
69+
70+
## Environment-specific credentials
71+
72+
API keys are scoped to a single environment. Requests authenticated with a secret key only access resources in that environment.
73+
74+
- **Development** — Build and test workflows, subscribers, and integrations.
75+
- **Production** — Send live notifications to subscribers.
76+
- **Custom environments** — Available on Team and Enterprise plans for staging, QA, or other release stages.
77+
78+
When you regenerate a secret key in the dashboard, the previous key is invalidated immediately. Update your environment variables before rotating keys in production.
79+
80+
## API base URLs
81+
82+
Use the base URL that matches your Novu Cloud region:
83+
84+
| Region | Base URL |
85+
| --- | --- |
86+
| **US (default)** | `https://api.novu.co/v1` |
87+
| **EU** | `https://eu.api.novu.co/v1` |
88+
89+
When using the EU region, also configure the WebSocket hostname for real-time Inbox updates:
90+
91+
| Region | WebSocket URL |
92+
| --- | --- |
93+
| **US (default)** | `wss://ws.novu.co` |
94+
| **EU** | `wss://eu.socket.novu.co` |
95+
96+
<Note>
97+
Self-hosted deployments use your own API hostname. See [Self Hosting Novu](/community/self-hosting-novu/overview) for configuration details.
98+
</Note>
99+
100+
## Security best practices
101+
102+
- Store secret keys in environment variables or a secrets manager — never commit them to version control.
103+
- Use separate credentials for development and production environments.
104+
- Rotate secret keys from the dashboard if a key may have been exposed.
105+
- Restrict server-side API access to trusted backend services only.
106+
- Enable [HMAC encryption](/platform/inbox/prepare-for-production#secure-your-inbox-with-hmac-encryption) for Inbox to prevent subscriber impersonation in client-side applications.
107+
108+
## Authentication errors
109+
110+
If authentication fails, the API returns a `401 Unauthorized` response. Common causes:
111+
112+
- Missing or malformed `Authorization` header
113+
- Secret key from a different environment than the target resources
114+
- Expired or regenerated secret key that has not been updated in your application
115+
116+
Verify that your header uses the `ApiKey` prefix (not `Bearer`) and that the secret key matches the active environment.
117+
118+
## Related documentation
119+
120+
- [Overview](/api-reference) — REST API capabilities and developer resources
121+
- [Rate Limiting](/api-reference/rate-limiting) — Request limits by plan and endpoint category
122+
- [Idempotency](/api-reference/idempotency) — Prevent duplicate requests by replaying responses for the same idempotency key
123+
- [Environments](/platform/developer/environments) — How environments isolate resources and credentials

‎docs/docs.json‎

Lines changed: 7 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -436,9 +436,10 @@
436436
"tab": "API Reference",
437437
"groups": [
438438
{
439-
"group": "Getting Started",
439+
"group": "Overview",
440440
"pages": [
441441
"api-reference",
442+
"api-reference/authentication",
442443
"api-reference/rate-limiting",
443444
"api-reference/idempotency",
444445
"api-reference/payload-limits"
@@ -1169,6 +1170,11 @@
11691170
"destination": "/api-reference",
11701171
"permanent": true
11711172
},
1173+
{
1174+
"source": "/api-reference/auth",
1175+
"destination": "/api-reference/authentication",
1176+
"permanent": true
1177+
},
11721178
{
11731179
"source": "/platform/workflow/overview",
11741180
"destination": "/platform/workflow",

0 commit comments

Comments
 (0)