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
| 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 |  |
| 14 | 6. Save, then copy the **Client ID** and **Client Secret**. |
| 15 | |
| 16 |  |
| 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 |  |
| 23 | |
| 24 |  |
| 25 | 2. Set the authentication type to **OAuth2** and choose **Use your own developer authentication**. |
| 26 | |
| 27 |  |
| 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 |  |
| 43 | |
| 44 |  |
| 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. |