# Confluence

SureCloud connects to Confluence to retrieve policy and procedure documents, page version history, and space-level permissions. This allows SureCloud to verify that key compliance documents — such as information security policies, acceptable use policies, and incident response procedures — exist, are current, and are accessible to the appropriate audiences. SureCloud also collects space access controls to confirm that sensitive documentation is restricted to authorised personnel.

## Authentication and setup

Confluence Cloud supports OAuth 2.0 for API access. SureCloud uses the Atlassian OAuth 2.0 flow to authenticate against your Confluence Cloud instance.

{% tabs %}
{% tab title="Confluence Cloud (OAuth 2.0)" %}
{% hint style="info" %}
SureCloud uses OAuth 2.0 for Confluence Cloud. 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 → Confluence → Connect**. Click **Authorise with Atlassian**. SureCloud will redirect you to the Atlassian authorisation page.
{% endstep %}

{% step %}

#### Select your Confluence site

Log in to Atlassian with an account that has Confluence Space Admin or Site Admin permissions. Select the Confluence site you want to connect and approve the requested scopes.
{% endstep %}

{% step %}

#### Return to SureCloud

After authorisation, you will be redirected back to SureCloud. The integration status will update to **Connected**. If your organisation has multiple Confluence sites, repeat this process for each site.
{% endstep %}
{% endstepper %}
{% endtab %}

{% tab title="Confluence Data Center / Server (API Token)" %}
{% stepper %}
{% step %}

#### Create a dedicated service account

In your Confluence Data Center or Server instance, create a dedicated user account (e.g. `surecloud-integration`) with read access to the spaces SureCloud needs to monitor. Avoid using a named employee account — service accounts ensure the connection remains active if the employee leaves.
{% endstep %}

{% step %}

#### Generate an API token

Log in as the service account. Navigate to **Profile → Personal Access Tokens** (Data Center) or generate credentials as required by your Confluence Server version. Create a token with read-only scope.
{% endstep %}

{% step %}

#### Enter the credentials in SureCloud

In SureCloud, go to **Integrations → Confluence → Connect (Server/Data Center)**. Enter your Confluence base URL, the service account username, and the API token. Click **Save** and then **Test Connection**.
{% endstep %}
{% endstepper %}

{% hint style="warning" %}
Store the API token securely. SureCloud encrypts it at rest, but you should treat it as a credential. Rotate it every 90 days and update it under **SureCloud → Integrations → Confluence → Edit Connection**.
{% endhint %}
{% endtab %}
{% endtabs %}

## Endpoints

| API Call                                              | Use Case                                                                           |
| ----------------------------------------------------- | ---------------------------------------------------------------------------------- |
| `GET /wiki/rest/api/space`                            | Enumerate all Confluence spaces; identify policy and compliance spaces             |
| `GET /wiki/rest/api/content?type=page&spaceKey={key}` | List pages within a space to locate policy and procedure documents                 |
| `GET /wiki/rest/api/content/{id}`                     | Retrieve page content and metadata including title, version, and last updated date |
| `GET /wiki/rest/api/content/{id}/version`             | Retrieve version history to confirm documents are reviewed and updated regularly   |
| `GET /wiki/rest/api/space/{key}/permission`           | Retrieve space permissions to verify access is restricted appropriately            |
| `GET /wiki/rest/api/group`                            | Enumerate Confluence groups used in space permission assignments                   |

## Pagination

`GET /wiki/rest/api/content` returns up to 25 results per request by default. SureCloud uses the `_links.next` path from each response to fetch subsequent pages until no `next` link is present.

```
GET /wiki/rest/api/content?type=page&spaceKey=IS&limit=50&start=50
```

`GET /wiki/rest/api/space` and `GET /wiki/rest/api/group` follow the same `start`/`limit` offset pattern. `GET /wiki/rest/api/content/{id}` and `GET /wiki/rest/api/content/{id}/version` return single objects or bounded version lists with no additional pagination.

## Required permissions / scopes

**Confluence Cloud (OAuth 2.0 scopes):**

| Scope                                | Purpose                                        |
| ------------------------------------ | ---------------------------------------------- |
| `read:confluence-space.summary`      | List spaces and retrieve space-level metadata  |
| `read:confluence-content.all`        | Read page content, titles, and version history |
| `read:confluence-content.permission` | Read space and page permissions                |
| `read:confluence-groups`             | Enumerate groups assigned to space permissions |

**Confluence Data Center / Server (service account permissions):**

The service account must have **View** permission on each space SureCloud needs to monitor. No edit or admin permissions are required.

## Polling frequency

| Data Type                              | Interval       |
| -------------------------------------- | -------------- |
| Policy and procedure page content      | Every 24 hours |
| Page version history                   | Every 24 hours |
| Space permissions and group membership | Every 24 hours |

## Troubleshooting

<details>

<summary>OAuth authorisation fails with "App not found" or redirects back with an error</summary>

This can occur if the OAuth application registration in Atlassian has not been approved or if the authorising user does not have Site Admin or Space Admin permissions. Ensure you are logging in with an account that has sufficient permissions, and retry from **SureCloud → Integrations → Confluence → Connect**.

</details>

<details>

<summary>Some spaces are missing from SureCloud's data collection</summary>

SureCloud only collects spaces that the authorised account (OAuth user or service account) has permission to view. If a space uses custom restrictions that exclude the integration account, SureCloud will not be able to read that space. Add the SureCloud service account or OAuth account to the relevant space permissions in Confluence and trigger a manual refresh.

</details>

<details>

<summary>Page content appears out of date in SureCloud</summary>

SureCloud polls page content every 24 hours. If a policy document was updated recently, the new version will appear after the next polling cycle. To force an immediate refresh, navigate to **SureCloud → Integrations → Confluence** and click **Refresh Now**.

</details>

<details>

<summary>Connection works but version history is incomplete</summary>

Confluence's version history API returns a maximum of 200 historical versions per page by default. For heavily edited documents, SureCloud may not capture the full edit history, though it will always have the current version and recent revisions. This is a Confluence API limitation and does not affect current document status evidence.

</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/confluence.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.