# Abnormal security

SureCloud connects to Abnormal Security to retrieve detected threat cases, attack campaign details, and automated remediation records. This allows SureCloud to verify that advanced email threat detection is active, that identified attacks are being captured and remediated, and that Abnormal's behavioural AI is operating against your email environment — providing continuous evidence for email security controls.

## Authentication and setup

Abnormal Security authenticates API requests using a Bearer token. SureCloud uses a token generated within the Abnormal Security portal.

{% stepper %}
{% step %}

### Generate an API token in Abnormal Security

Log in to the Abnormal Security portal at [portal.abnormalsecurity.com](https://portal.abnormalsecurity.com/). Navigate to **Settings → Integrations → API** and click **Generate Token**. Give it a name such as `SureCloud CCM`. Copy the token — it is only shown once.
{% endstep %}

{% step %}

### Enter the token in SureCloud

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

{% step %}

### Test the connection

Click **Test Connection**. SureCloud will call `GET /v1/cases` to verify the token and confirm threat data is accessible.
{% endstep %}
{% endstepper %}

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

## Endpoints

| API Call                          | Use Case                                                                                    |
| --------------------------------- | ------------------------------------------------------------------------------------------- |
| `GET /v1/cases`                   | Retrieve all detected threat cases including attack type and current status                 |
| `GET /v1/cases/{case_id}`         | Retrieve individual case detail including affected recipients and attack timeline           |
| `GET /v1/threats`                 | Retrieve threat message records for individual email-level threat evidence                  |
| `GET /v1/threats/{threat_id}`     | Retrieve individual threat message detail including sender, subject, and remediation action |
| `GET /v1/abuse-mailbox/campaigns` | Retrieve user-reported phishing campaigns submitted via the abuse mailbox                   |

## Pagination

`GET /v1/cases` and `GET /v1/threats` use page token pagination. SureCloud uses the `nextPageNumber` value from each response as the `pageNumber` parameter in the next request, continuing until no `nextPageNumber` is returned.

```json
GET /v1/cases?pageSize=100&pageNumber=2
```

`GET /v1/abuse-mailbox/campaigns` uses the same pattern.

## Required permissions

Abnormal Security API tokens are account-scoped and provide read-only access to threat detection and case data by default. No configuration-change, remediation-trigger, or admin permissions are required.

## Polling frequency

| Data Type                         | Interval       |
| --------------------------------- | -------------- |
| Threat cases and attack campaigns | Every 4 hours  |
| Individual threat message records | Every 4 hours  |
| Abuse mailbox campaign reports    | Every 24 hours |

## Troubleshooting

<details>

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

The API token is invalid or has been revoked. Navigate to **Abnormal Security → Settings → Integrations → API**, confirm the token is active, and regenerate it if necessary. Update it in **SureCloud → Integrations → Abnormal Security → Edit Connection**.

</details>

<details>

<summary>Cases list returns empty despite active threats in the portal</summary>

Newly detected cases may take up to 15 minutes to appear via the API after being visible in the portal. SureCloud will collect them on the next polling cycle. If cases are persistently missing, confirm the API token account has full portal access and that no IP allowlist is restricting API access to the token.

</details>

<details>

<summary>Abuse mailbox campaigns endpoint returns 404</summary>

The abuse mailbox feature requires the Abnormal Security Abuse Mailbox add-on to be enabled for your account. If your organisation has not activated this feature, the endpoint will return 404. SureCloud will continue to collect case and threat data from the other endpoints.

</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/abnormal-security.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.