# Bitsight

```yaml
---
description: Connect BitSight to SureCloud to collect external security ratings, vendor cyber risk scores, and findings evidence for third-party risk management controls.
icon: chart-line
---
```

## BitSight

SureCloud connects to BitSight to retrieve security ratings, risk vector findings, and vendor portfolio data. This allows SureCloud to incorporate external cyber risk scores into your compliance evidence — confirming that your organisation's BitSight rating is being tracked, that vendor security posture is being monitored, and that changes in rating are being captured for third-party risk management controls.

### Authentication and setup

BitSight authenticates API requests using an API token associated with your BitSight account.

{% stepper %}
{% step %}

### Generate an API token in BitSight

Log in to your BitSight account at [service.bitsighttech.com](https://service.bitsighttech.com/). Navigate to **Account → API Token** (or **Settings → Integrations → API**) and click **Generate Token**. Copy the token.
{% endstep %}

{% step %}

### Enter the token in SureCloud

Navigate to **SureCloud → Integrations → BitSight → Connect**. Paste the API token and click **Save**.
{% endstep %}

{% step %}

### Test the connection

Click **Test Connection**. SureCloud will call `GET /ratings/v1/companies` to verify the token and confirm access to rating data.
{% endstep %}
{% endstepper %}

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

### Endpoints

| API Call                                          | Use Case                                                                |
| ------------------------------------------------- | ----------------------------------------------------------------------- |
| `GET /ratings/v1/companies`                       | Retrieve your organisation's current security rating and rating history |
| `GET /ratings/v1/companies/{guid}/findings`       | Retrieve risk vector findings driving the current rating                |
| `GET /ratings/v1/portfolio`                       | Enumerate vendor portfolio companies and their ratings                  |
| `GET /ratings/v1/companies/{guid}/rating-details` | Retrieve detailed rating breakdown by risk vector                       |
| `GET /ratings/v2/companies/{guid}/risk-vectors`   | Retrieve individual risk vector scores and evidence                     |

### Pagination

`GET /ratings/v1/companies/{guid}/findings` uses offset-based pagination. SureCloud increments `offset` by the page size until all findings are retrieved.

```json
GET /ratings/v1/companies/{guid}/findings?limit=100&offset=100
```

`GET /ratings/v1/portfolio` returns all portfolio companies in a single response for most accounts.

### Required permissions

BitSight API tokens are account-scoped and provide read-only access to ratings, findings, and portfolio data by default. No write or configuration permissions are required.

### Polling frequency

| Data Type                    | Interval       |
| ---------------------------- | -------------- |
| Organisation security rating | Every 24 hours |
| Risk vector findings         | Every 24 hours |
| Vendor portfolio ratings     | Every 24 hours |

### Troubleshooting

<details>

<summary>Connection test returns 401 Unauthorized</summary>

The API token is invalid or has been revoked. Navigate to **BitSight → Account → API Token**, regenerate the token, and update it in **SureCloud → Integrations → BitSight → Edit Connection**.

</details>

<details>

<summary>Portfolio vendor list is empty</summary>

The portfolio endpoint only returns companies that have been added to your BitSight vendor portfolio. If no vendors have been added, the response will be empty. Add vendors to your portfolio in the BitSight console to populate this data.

</details>

<details>

<summary>Findings data is incomplete for some risk vectors</summary>

BitSight findings are dependent on the external scan data available for your IP ranges and domains. Risk vectors with limited externally observable data may have fewer findings than others. This reflects BitSight's data collection scope and not a SureCloud collection issue.

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