> ## Documentation Index
> Fetch the complete documentation index at: https://support.configview.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Notion setup

ConfigView pulls Notion data through a **single workspace integration token** that you create in your Notion workspace. The token only sees pages and databases the integration has been explicitly added to — so the inventory reflects what the integration is *shared with*, not your full workspace.

You will end up with **1 secret** in ConfigView (`NOTION_TOKEN`) when setup is complete.

> **Important visibility caveat.** Notion's workspace API does not expose a complete user list, a complete page list, or "all installed integrations" on Team or Business plans. ConfigView sees exactly what your integration has been invited to. To inventory **every** integration installed in the workspace, or to ingest the full audit log, you need a **Notion Enterprise** plan and the **Audit Log API** — that is a separate setup and is not covered here yet.

***

## Step 1: Create the Notion integration

1. Sign in to your Notion workspace as a **Workspace Owner** at [https://www.notion.so](https://www.notion.so)
2. Open [https://www.notion.so/profile/integrations](https://www.notion.so/profile/integrations) (or **Settings** → **My connections** → **Develop or manage integrations**)
3. Click **+ New integration**
4. **Name:** `ConfigView`
5. **Associated workspace:** pick the workspace ConfigView should inventory
6. **Type:** **Internal**
7. **Capabilities:** ConfigView only reads data. Enable the read capabilities:
   * **Read content**
   * **Read comments**
   * **Read user information including email addresses**
8. Click **Save**
9. On the next screen, copy the **Internal Integration Secret** (starts with `ntn_` or `secret_`). You will not be able to see it again — store it somewhere safe.

***

## Step 2: Share pages and databases with the integration

The integration starts with **zero access**. You must explicitly share each top-level page or database you want ConfigView to see — sub-pages inherit access from their parent.

The fastest way to inventory broadly:

1. Open the top-level **workspace page** (or each top-level page you want inventoried)
2. Click the **`...`** menu in the top-right → **Connections** → **Add connections**
3. Search for **ConfigView** and click to add it
4. Repeat for each top-level page or database

> **Tip:** If you want ConfigView to see everything, share a single top-level page that contains (or is the ancestor of) all the content you care about. Nested pages and databases inherit access automatically.

***

## Step 3: Add the secret to ConfigView

1. Go to your ConfigView dashboard: `https://{companyname}.configview.com/admin/secret/`
2. Click **Add Secret**
3. **Secret name:** `NOTION_TOKEN`
4. **Secret value:** Paste the Internal Integration Secret from Step 1
5. Click **Save**

***

## Step 4: Enable the Notion scripts in ConfigView

1. Go to: `https://{companyname}.configview.com/admin/cron/`
2. You should see **notion** in the list of available apps
3. Select the scripts you want to run:

| Script                   | Notes                                                                                                                                                 |
| ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Bot Token Introspect** | Validates the token and records the workspace name/bot owner. Safe to always enable.                                                                  |
| **Users**                | Workspace members + bots the integration can see. Person users include email; bots include owner info.                                                |
| **Databases**            | Every database shared with the integration.                                                                                                           |
| **Database Rows**        | Rows inside each database. **Depends on Databases.**                                                                                                  |
| **Pages**                | Every page shared with the integration.                                                                                                               |
| **Blocks**               | Top-level blocks for each page (paragraphs, headings, lists, etc.). **Depends on Pages.** **Top-level only — does not recurse into nested children.** |
| **Comments**             | Comments on each page. **Depends on Pages.**                                                                                                          |
| **Search Index**         | A flat catalog of every object (page + database) visible to search. Useful for discovery and cross-checking what the integration can see.             |

4. Click **Save**

> **Note:** Database Rows depends on Databases; Blocks and Comments depend on Pages. ConfigView wires these dependencies automatically — parent scripts always run first.

***

## Step 5: Verify

1. Go to: `https://{companyname}.configview.com/admin/status/`
2. Run the **Notion** health check
3. The check should pass with the workspace name from your introspect

If a check fails:

* **`401 Unauthorized`** — Token was revoked or copied incorrectly. Re-issue from Step 1 and update the `NOTION_TOKEN` secret.
* **`Users` returns zero or only bots** — Notion's `/users` endpoint requires the **Read user information** capability. Edit the integration (Step 1, item 7) to enable that capability and retry.
* **`Databases` or `Pages` returns zero** — The integration has not been added as a connection on any page yet. Repeat Step 2.

***

## Data Tables

Once the scripts run, the corresponding tables are created in your database. All tables include a `run_at` column for historical tracking.

| Table                  | Source                              | Key Columns                                                                                   |
| ---------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------- |
| `notion_introspect`    | `GET /v1/users/me`                  | bot\_id, bot\_name, workspace\_name, owner\_type, capabilities\_json                          |
| `notion_users`         | `GET /v1/users`                     | user\_id, type (person/bot), name, email, bot\_owner\_type                                    |
| `notion_databases`     | `POST /v1/search` (filter=database) | database\_id, title, parent\_type, parent\_id, archived, last\_edited\_time, properties\_json |
| `notion_database_rows` | `POST /v1/databases/{id}/query`     | database\_id, page\_id, archived, last\_edited\_time, properties\_json                        |
| `notion_pages`         | `POST /v1/search` (filter=page)     | page\_id, title, parent\_type, parent\_id, archived, public\_url, last\_edited\_time          |
| `notion_blocks`        | `GET /v1/blocks/{id}/children`      | block\_id, page\_id, type, plain\_text, has\_children                                         |
| `notion_comments`      | `GET /v1/comments`                  | comment\_id, page\_id, discussion\_id, created\_by\_user\_id, plain\_text                     |
| `notion_search`        | `POST /v1/search` (no filter)       | object\_id, object\_type, title, url, last\_edited\_time                                      |

***

## What you can't ingest with this setup

Two questions ConfigView **cannot** answer with a workspace integration token alone:

1. **"What integrations are installed in our Notion workspace?"** Notion's public API does not expose a workspace-wide integrations list. The only supported path is the **Audit Log API** on Notion Enterprise, scanning for `integration.add` and `integration.remove` events.
2. **"List every user in our Notion workspace."** The `/users` endpoint returns workspace people and visible bots, but on Team/Business plans some users (especially guests) may not appear unless the integration has been added to content they touch. For a complete directory, use **Notion SCIM** on Enterprise.

If either is a hard requirement, ask your ConfigView contact about the Enterprise expansion — it's planned but not yet shipped.