@devries-cameron20 / composio Mirror · read-only
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 06:00 UTC

next
md 153 lines 8.52 KB
Rendered Raw
1 ## How do I set up custom OAuth credentials for Notion?
2
3 Use your own Notion integration when you want your own name and logo on the consent screen and in Notion's activity, or to keep your users' tokens isolated to your product.
4
5 ### Create the Notion integration
6
7 1. Go to [Notion integrations](https://www.notion.so/profile/integrations) and click **New integration**.
8 2. Enter a name, such as `Composio Notion Integration`, and select the associated workspace.
9 3. Set the integration type to **Public**. Composio's OAuth flow requires a public integration.
10 4. Under **OAuth domains & URIs**, add the redirect URI `https://backend.composio.dev/api/v1/auth-apps/add`. Use it exactly as shown: HTTPS, no trailing slash, no fragments or wildcards. It must exactly match the `oauth_redirect_uri` field in your Composio auth config.
11 5. Under **Capabilities**, select only what your integration needs, such as **Read content**, **Update content**, **Insert content**, and **Read user information**. Notion uses capabilities instead of OAuth scopes.
12
13 ![Notion integration Capabilities section with content and user capabilities](/images/toolkits/notion/capabilities.webp)
14 6. Save, then copy the **Client ID** and **Client Secret**.
15
16 ![Notion integration configuration with redacted OAuth Client ID and hidden Client Secret](/images/toolkits/notion/oauth-credentials.webp)
17
18 ### Create the auth config in Composio
19
20 1. In the Composio dashboard, go to **Auth Configs**, click **Create Auth Config**, and select **Notion**.
21
22 ![Composio Auth Configs page with the Create Auth Config button](/images/toolkits/shared/wIAvY0hheAM7HQEF4kG2KTYATY.webp)
23
24 ![Create Auth Config search results showing Notion](/images/toolkits/notion/composio-search-notion.webp)
25 2. Set the authentication type to **OAuth2** and choose **Use your own developer authentication**.
26
27 ![Notion auth config with OAUTH2 selected and the Use your own developer credentials toggle](/images/toolkits/notion/oauth2-auth-config.webp)
28 3. Paste the **Client ID** and **Client Secret** and click **Create Notion Auth Config**. Leave scopes empty.
29 4. Click **Connect Account**, choose the pages to share during Notion's authorization, and confirm the account shows as **Active**.
30
31 See [Custom auth configs](/docs/auth-configuration/custom-auth-configs) for the general flow.
32
33 ## How do I connect Notion with an API key?
34
35 Use an internal integration secret when you connect your own workspace, don't need multi-user OAuth, and want to skip the redirect flow. API keys only work with internal integrations; public integrations must use OAuth.
36
37 1. On [Notion integrations](https://www.notion.so/profile/integrations), click **New integration**, enter a name, select the workspace, and set the type to **Internal**.
38 2. Copy the integration secret. It starts with `ntn_` or `secret_`.
39 3. Share the pages and databases you want Composio to reach with the integration. The integration can only access pages shared with it.
40 4. In the Composio dashboard, create a **Notion** auth config with the **API Key** auth type. Click **Connect Account**, paste the secret, and confirm the account shows as **Active**.
41
42 ![Notion auth config with API KEY selected as the authentication method](/images/toolkits/notion/api-key-auth-config.webp)
43
44 ![Composio connect screen with a redacted Notion API key](/images/toolkits/notion/connect-api-key.webp)
45
46 ## Why do Notion operations show "Composio" instead of the user's name?
47
48 Notion attributes actions to the integration itself, not the individual user. The name and logo shown come from the integration configuration. To use a custom name or logo, create your own Notion integration. See [Notion integration docs](https://developers.notion.com/docs/create-a-notion-integration).
49
50 ## How do I grant access to more Notion pages?
51
52 Open Notion, go to Settings & Members, then Connections. Select the integration (Composio or your custom integration), click "Select pages" or "Manage access", and add or remove pages as needed.
53
54 ## Does Notion use OAuth scopes?
55
56 No. Notion controls access by granting integrations access to specific pages and databases, not through scopes. You don't need to pass scopes when creating an auth config.
57
58 ## How does Notion's access model work?
59
60 It depends on the integration type. OAuth apps (public) let users select which pages to share during authorization. Internal integrations (API key) have page access managed in the integration settings.
61
62 ## Reasons for Notion Connection expiry
63
64 - **The user disconnects the integration from Notion.** Notion documents that OAuth-installed public connections appear under `Settings` -> `Connections` and can be disconnected from the workspace. If a user removes the Composio-managed or custom Notion app there, the existing token set should be treated as revoked, and the user should reconnect Notion. See Notion's official guide to [adding and managing workspace connections](https://www.notion.com/help/add-and-manage-connections-with-the-api).
65
66 - **The same Notion user connects again through the same Notion app.** When a Notion user connects to a Notion app, Notion issues a new `access_token` and `refresh_token` pair for that connection. If the same user connects to the same Notion app again, whether it is Composio-managed or custom, Notion can issue a new token pair and invalidate the older `refresh_token`. The older `access_token` may continue working for some time, but once it expires, the older connection can no longer refresh and should be treated as expired. To avoid this, keep one active Notion connection per real user for a given Notion app, reuse that existing connection in your product, and avoid asking users to reconnect repeatedly. For production Notion integrations, we strongly recommend using your own Notion app so your users' tokens are isolated to your product. See "How do I set up custom OAuth credentials for Notion?" on this page for the steps.
67
68 ## How do I set up the Notion webhook ingress endpoint?
69
70 With Composio-managed Notion credentials, the webhook ingress endpoint is already provisioned, so just create the trigger. If you bring your own Notion OAuth app, the verification flow runs in reverse from Slack's: Notion sends a verification token to the ingress endpoint, and you paste that token back into Notion to finalize.
71
72 ### Create the endpoint
73
74 #### Python
75
76 ```python
77 from composio import Composio
78
79 composio = Composio()
80 endpoint = composio.webhooks.endpoints.create(
81 toolkit_slug="notion",
82 client_id="YOUR_NOTION_OAUTH_CLIENT_ID",
83 )
84 print(endpoint.root.id, endpoint.root.webhook_url)
85 ```
86
87 #### TypeScript
88
89 ```typescript
90 import { Composio } from '@composio/core';
91
92 const composio = new Composio();
93 const endpoint = await composio.webhooks.endpoints.create({
94 toolkitSlug: 'notion',
95 clientId: 'YOUR_NOTION_OAUTH_CLIENT_ID',
96 });
97 console.log(endpoint.id, endpoint.webhookUrl);
98 ```
99
100 #### API
101
102 ```bash
103 curl -X POST https://backend.composio.dev/api/v3.1/webhook_endpoints \
104 -H "x-api-key: $COMPOSIO_API_KEY" \
105 -H "Content-Type: application/json" \
106 -d '{"toolkit_slug": "notion", "client_id": "YOUR_NOTION_OAUTH_CLIENT_ID"}'
107 ```
108
109 ### Complete Notion verification
110
111 Save the returned `id` and `webhook_url`. Paste `webhook_url` into your Notion integration's Webhook settings. Notion sends a verification token to that URL.
112
113 Replace `we_123` with the saved endpoint ID and read the token:
114
115 #### Python
116
117 ```python
118 from composio import Composio
119
120 composio = Composio()
121 endpoint = composio.webhooks.endpoints.get("we_123")
122 token = endpoint.data.get("webhook_signing_secret") if endpoint.data is not None else None
123 if token is None:
124 raise RuntimeError("Notion has not sent a verification token yet")
125 print(token)
126 ```
127
128 #### TypeScript
129
130 ```typescript
131 import { Composio } from '@composio/core';
132
133 const composio = new Composio();
134 const endpoint = await composio.webhooks.endpoints.get('we_123');
135 const token = endpoint.data?.webhook_signing_secret;
136 if (token == null) throw new Error('Notion has not sent a verification token yet');
137 console.log(token);
138 ```
139
140 #### API
141
142 ```bash
143 curl -s https://backend.composio.dev/api/v3.1/webhook_endpoints/we_123 \
144 -H "x-api-key: $COMPOSIO_API_KEY" | jq -er '.data.webhook_signing_secret // error("Notion has not sent a verification token yet")'
145 ```
146
147 <!-- end-languages -->
148
149 Paste the token back into Notion's verify field to complete setup. Continue with [Creating triggers](/docs/setting-up-triggers/creating-triggers#create-the-trigger).
150
151 ## Notion database trigger fires for new pages, not updates
152
153 In manual testing, the Notion trigger fired when pages were added to the watched database, but not for updates. Test by adding a new page to the target database.