> For the complete documentation index, see [llms.txt](https://herd-security.gitbook.io/herd-security-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://herd-security.gitbook.io/herd-security-docs/policies/notion-integration.md).

# Notion Integration

Connect your Notion workspace to Herd with your own Notion OAuth integration, then link policies to Notion pages so Herd AI answers from the live document.

If your policies live in Notion, you can link a Herd policy to a Notion page instead of uploading a copy. Herd reads the page through a Notion integration that you register, indexes its content so Herd AI answers from the document, and re-reads every linked page daily so the indexed copy tracks your edits. Herd only reads. It doesn't change your pages.

Setup has three parts.

1. [Register a Notion integration](#part-1-register-a-notion-integration).
2. [Connect it in Herd](#part-2-connect-it-in-herd).
3. [Link policies to Notion pages](#part-3-link-policies-to-notion-pages).

## Before you start

* You are a Herd admin with Integrations permissions.
* You can create an integration in your Notion workspace.

## Part 1: Register a Notion integration

Each organization connects its own Notion workspace by registering a Notion OAuth integration (a public integration) and pasting its credentials into Herd.

### Step 1: Copy the redirect URI from Herd

In Herd, go to **Settings → Integrations** and open the **Notion** card (in the **Knowledge & Policies** section). The same setup also opens from **Policies → Library**: under **Sources**, select **Connect** on **Notion**. The card shows a **Redirect URI (paste into your Notion integration)**. Use the copy button next to it. The URI is specific to your Herd environment, so always copy it from the card.

### Step 2: Create the integration in Notion

Create a public integration in Notion and paste the redirect URI into its **Redirect URIs** field exactly as shown.

Notion has no scope setting for an OAuth request. What the integration can do is set when you create it, and it can only see the pages you share with it. Herd only reads pages, so the integration needs no more than the capability to read content.

### Step 3: Copy the client ID and secret

From the integration's settings in Notion, copy the **OAuth client ID** and the **OAuth client secret**. Treat the secret like a password. Herd stores it encrypted and doesn't show it again.

## Part 2: Connect it in Herd

### Step 1: Save the credentials

On the **Notion** card, paste the values into **Notion OAuth client ID** and **Notion OAuth client secret**, then select **Save credentials**.

### Step 2: Authorize Herd

1. Select **Connect to Notion**. Herd opens Notion's consent screen.
2. Choose the workspace, and the pages to share if Notion asks, and accept.

Notion sends you back to **Settings → Integrations**, even if you started from the Library. The card now shows the workspace name and when the connection was last checked. Select **Check connection** to run a live check straight away. If the check fails, the card shows **token invalid**.

{% hint style="warning" %}
Herd can read only the pages shared with the integration. A page that isn't shared with it is invisible to Herd, and a policy linked to it ends up with no content. In Notion, open the page's **Share** menu and add the integration, or share its parent page.
{% endhint %}

## Part 3: Link policies to Notion pages

### Step 1: Copy the page URL

Open the page in Notion and copy its address. Herd recognizes these forms:

* `https://www.notion.so/Page-Title-<32-character-id>`
* `https://www.notion.so/<workspace>/Page-Title-<32-character-id>`
* `https://notion.so/<32-character-id>`
* `https://<workspace>.notion.site/Page-Title-<32-character-id>`

Herd finds the page by the 32-character ID at the end of the address.

### Step 2: Create the policy

1. Go to **Policies → Library** and select **Create Policy**.
2. Choose **External Link** and paste the page URL.
3. Continue through the remaining steps as for any other policy (see [Creating a Policy](https://herd-security.gitbook.io/herd-security-docs/policies/policies.md#creating-a-policy)).

You can also link an existing policy to a Notion page by editing it and switching its document to **External Link**.

### What happens next

* Herd reads the page when the policy is saved and adds its content to the knowledge index that grounds Herd AI, so members can ask the Herd bot what a policy says.
* Herd re-reads every active policy linked to a Notion page once a day, so edits you make in Notion reach Herd AI's answers within a day. Nothing needs re-uploading.
* Herd reads only the pages an admin has linked as policies. It skips organizations that have no active Notion connection.

## Maintain the connection

Once connected, the Notion card offers:

* **Check connection**, a live request that records the result and time on the card.
* **Re-enter credentials**, which replaces the client ID and secret. Saving new credentials resets the authorization, so select **Connect to Notion** again afterwards.
* **Disconnect**, which stops Herd reading from Notion and clears the stored client secret and access token. To reconnect, save the credentials again. Policies you linked keep their links but stop updating.

Until authorization completes, the card shows **Connect to Notion** and **Re-enter credentials**.

## Herd AI and Notion

Admins with the integrations permission can ask HerdAI to search or read pages in the connected workspace. Everyone else gets answers only from the pages linked as policies. Both use the same read-only connection, and only pages shared with the integration are visible.
