# Notion

SureCloud connects to Notion to retrieve pages, databases, and workspace member information. This allows SureCloud to confirm that policy documents and compliance procedures stored in Notion exist, are being maintained, and are accessible only to authorised personnel. SureCloud also collects workspace membership and guest access records to support access control monitoring.

## Authentication and setup

Notion uses OAuth 2.0 for third-party integrations. SureCloud connects via a Notion OAuth app authorised by a workspace admin.

{% hint style="info" %}
SureCloud uses OAuth 2.0 for this integration. No credentials are stored — access is maintained via a refresh token that SureCloud rotates automatically.
{% endhint %}

{% stepper %}
{% step %}
**Initiate the connection in SureCloud**

Navigate to **SureCloud → Integrations → Notion → Connect** and click **Authorise with Notion**. SureCloud will redirect you to the Notion authorisation page.
{% endstep %}

{% step %}
**Select pages and databases to share**

Log in to Notion with a Workspace Owner or Admin account. Notion's OAuth flow requires you to explicitly select which pages and databases SureCloud can access. Select the top-level pages that contain your policy documents, compliance databases, and vendor questionnaire records. SureCloud will have access to those pages and all their children.
{% endstep %}

{% step %}
**Approve the connection**

Click **Allow Access**. You will be redirected back to SureCloud with the integration status updated to **Connected**.
{% endstep %}

{% step %}
**Expand page access if needed**

If SureCloud needs access to additional pages that were not selected during the initial authorisation, navigate to **SureCloud → Integrations → Notion → Edit Connection** and click **Update Page Access** to re-run the Notion page selector.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Notion's OAuth model requires you to explicitly grant page access during authorisation. Pages not selected during setup will not be visible to SureCloud, even if they are in the same workspace. Review the page selection carefully to ensure all relevant compliance content is included.
{% endhint %}

## Endpoints

| API Call                        | Use Case                                                                                   |
| ------------------------------- | ------------------------------------------------------------------------------------------ |
| `POST /v1/search`               | Search for pages and databases within the authorised scope                                 |
| `GET /v1/pages/{id}`            | Retrieve page metadata including title, created time, and last edited time                 |
| `GET /v1/blocks/{id}/children`  | Retrieve page content blocks to confirm document exists and has substantive content        |
| `GET /v1/databases/{id}`        | Retrieve database schema and metadata for vendor questionnaire and risk register databases |
| `POST /v1/databases/{id}/query` | Query database entries to collect vendor questionnaire responses or evidence items         |
| `GET /v1/users`                 | Enumerate workspace members and their roles                                                |
| `GET /v1/users/{id}`            | Retrieve individual user details including guest or member status                          |

## Pagination

`POST /v1/search`, `GET /v1/blocks/{id}/children`, and `POST /v1/databases/{id}/query` all support cursor-based pagination. SureCloud uses the `next_cursor` value from each response as the `start_cursor` parameter in the next request, continuing until `has_more` is `false`.

```json
POST /v1/databases/{id}/query
{
  "start_cursor": "<value_from_previous_response>",
  "page_size": 100
}
```

`GET /v1/users` also uses cursor-based pagination with the same `next_cursor` / `start_cursor` pattern.

## Required permissions / scopes

SureCloud requests the following OAuth capabilities from Notion:

| Capability            | Purpose                                                                              |
| --------------------- | ------------------------------------------------------------------------------------ |
| Read content          | Access page content, block content, and database entries within the authorised pages |
| Read user information | Enumerate workspace members and their access level                                   |

No write or insert capabilities are requested.

## Polling frequency

| Data Type                                                  | Interval       |
| ---------------------------------------------------------- | -------------- |
| Policy page content and last-edited timestamps             | Every 24 hours |
| Database entries (vendor questionnaires, evidence records) | Every 24 hours |
| Workspace member list and roles                            | Every 24 hours |

## Troubleshooting

<details>

<summary>Expected pages are not appearing in SureCloud</summary>

Notion requires explicit page selection during OAuth authorisation. If a page was not selected when the connection was established, SureCloud cannot access it. Go to **SureCloud → Integrations → Notion → Edit Connection** and click **Update Page Access** to re-run the page selector and add the missing pages.

</details>

<details>

<summary>Workspace member list is incomplete</summary>

`GET /v1/users` only returns members of the workspace that the authorising account has permission to enumerate. If your Notion workspace uses SAML SSO and restricts user directory access, some members may not be returned. Check your Notion workspace settings under **Settings & Members → Members** to confirm the authorising account has member visibility.

</details>

<details>

<summary>Database query returns no results despite entries being present in Notion</summary>

This can occur if a database was not included in the page access granted during OAuth setup. Databases in Notion must be explicitly shared with the integration — sharing a parent page does not automatically share all databases nested within it in all cases. Re-run the page selector from **SureCloud → Integrations → Notion → Edit Connection** and explicitly include the relevant database pages.

</details>

<details>

<summary>OAuth connection drops after workspace changes</summary>

If a Notion Workspace Owner revokes the SureCloud integration or changes workspace-level API access settings, the OAuth token will be invalidated. Navigate to **SureCloud → Integrations → Notion → Reconnect** and complete the OAuth flow again to restore the connection.

</details>


---

# Agent Instructions: Querying This Documentation

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

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/notion.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.