> For the complete documentation index, see [llms.txt](https://docs.elimity.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.elimity.com/notion/step-by-step-deployment-guide.md).

# Step-by-step deployment guide

The Notion connector imports the users of your Notion workspaces into Elimity Insights, with their workspace role and permission groups on the Enterprise plan.

## 1. Which data is imported from Notion?

What the gateway can import depends on your Notion plan, because the workspace role (owner, membership admin, member, restricted member) and the permission groups are only available through Notion's Admin API, which requires the **Enterprise** plan.

|                                                                                        | Enterprise plan (Admin API) | Other plans (Notion API) |
| -------------------------------------------------------------------------------------- | --------------------------- | ------------------------ |
| `Users`: people and bots, with name, email and type                                    | ✓                           | ✓                        |
| `Workspaces`                                                                           | ✓                           | —                        |
| `Workspace Roles`: Owner, Membership admin, Member and Restricted member per workspace | ✓                           | —                        |
| `Groups`: permission groups, with the user's group role (owner or member)              | ✓                           | —                        |

Access runs User → Workspace Role → Workspace, for example *Jane → "Acme - Owner" → Acme*. All four workspace roles exist for every workspace, also when nobody holds them.

```mermaid
graph TD
User[User]
WorkspaceRole[Workspace Role]
Workspace[Workspace]
Group[Group]
User --> WorkspaceRole --> Workspace
User -->|Group role| Group
```

#### Data model

| Entity type    | Attributes                                                                                                          |
| -------------- | ------------------------------------------------------------------------------------------------------------------- |
| User           | `Email` (absent for bots; the key to match users to your other sources), `Type` (Person or Bot), `Is bot`           |
| Workspace      | name only                                                                                                           |
| Workspace role | `Type` (Owner, Membership admin, Member or Restricted member), `Workspace`, `Is admin` (Owner and Membership admin) |
| Group          | `Group name`, `Workspace`                                                                                           |

| Relationship               | Attributes                                                  |
| -------------------------- | ----------------------------------------------------------- |
| User → Workspace role      | —                                                           |
| Workspace role → Workspace | —                                                           |
| User → Group               | `Group role`: the user's role in the group, Owner or Member |

Workspace roles are named after their workspace, for example "Acme - Owner", and groups likewise, for example "Acme - Finance". A user who is in two workspaces is imported once, with a role in each workspace.

Not imported: teamspaces and their members (no Notion API exposes them), page-level sharing and page guests (not listed by the Notion API).

## 2. Create a token in Notion

### 2a. Enterprise plan: Admin API organization bot

An **organization owner** creates an organization bot in the Notion organization console and gives it only these read scopes:

* `workspace:read`
* `user:read`
* `permission-group:read`

Note down the token. See [Notion's Admin API documentation](https://developers.notion.com/reference/admin/intro) for details. The scopes are read-only: the gateway never changes anything in Notion.

### 2b. Other plans: developer connection

On a plan without the Admin API, the gateway reads the users through a developer connection (Notion's docs call it an internal connection). You must be a **Workspace Owner** to create one.

* In Notion, open **Developer tools** and go to the **Developer connections** tab (or open the [Developer portal](https://app.notion.com/developers/connections) directly).
* Click **New connection** and create a connection for your workspace only, for example named `Elimity Insights`.
* On the connection's **Configuration** tab, set the user capability to **User information with email addresses**. Without a user information capability, Notion refuses the user list with `403`; without email addresses, users can't be matched to your other sources.
* Copy the **API token** from the **Configuration** tab.

See Notion's guide on [internal connections](https://developers.notion.com/guides/connections-and-tokens/internal-connections) and [capabilities](https://developers.notion.com/reference/capabilities). A personal access token does not work: it can't list the workspace users.

## 3. Configure the source in Elimity Insights

* Go to 'Sources' in the left navigation bar and click 'Add Source'.
* Search for 'Custom' and click 'Set Up'.
* Click 'Set Up' again and fill in the name of the Source (e.g. Notion).
* Select 'Upload export file'.
* Click 'Continue' and upload the data model export file `notion-data-model-export.json`:

{% file src="/files/70UUqJF12NuApIGQIsws" %}

* Now go to the 'Config' tab and click 'Edit'.
* Set 'Enable automatic imports via custom gateway' to true and fill in the Gateway URL: `https://notion-gateway-1027270379075.europe-west1.run.app` for the gateway hosted by Elimity, or the URL of your own deployment.
* Set 'SDK version' to `2`.
* Click 'Add configuration value' and add **one** of these, depending on your plan:

| Key                 | Type       | Description                                                                                                      |
| ------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------- |
| `admin_token`       | `Password` | Enterprise plan: the organization bot token from step 2a. Imports users, workspaces, workspace roles and groups. |
| `integration_token` | `Password` | Other plans: the API token of the developer connection from step 2b. Imports users only.                         |

Set only one of the two: with both, the import stops with `Invalid config`.

Now click 'Save and run'! You can monitor the progress in the 'Logs' tab. The import log starts with the mode that ran: the Admin API (Enterprise) or the Notion API (users only).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.elimity.com/notion/step-by-step-deployment-guide.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
