# Datadog

Connecting Datadog gives SureCloud read access to your Datadog organisation's monitors, log pipelines, audit trail events, and user access configuration. SureCloud verifies that critical security alerts are defined and active, checks that log indexes are configured with appropriate retention periods, reviews audit trail coverage to confirm that administrative activity is being captured, and audits user and team access within the Datadog console. This provides continuous evidence that your monitoring and logging infrastructure is operational and appropriately governed.

{% hint style="info" %}
SureCloud connects to Datadog using an API Key and Application Key pair. These are generated in the Datadog console and scoped to the minimum permissions SureCloud requires. No OAuth flow is involved — credentials are stored encrypted at rest in SureCloud.
{% endhint %}

## Authentication and setup

{% stepper %}
{% step %}

#### Create a dedicated service account in Datadog

In the Datadog console, navigate to **Organisation Settings → Users → Invite Users** and create a dedicated service user for SureCloud (e.g. `surecloud-ccm@yourcompany.com`). Assign the **Datadog Read Only** role.

Using a dedicated account ensures the API keys SureCloud uses are not tied to a personal user account that may be deactivated.
{% endstep %}

{% step %}

#### Generate an API Key

In **Organisation Settings → API Keys → New Key**, create a key named `SureCloud CCM`. Copy the key value immediately — it is only shown once.

{% hint style="warning" %}
API Keys are not scoped by permission — they authenticate requests at the organisation level. Restrict access to this key value and rotate it every 90 days, updating the value in **SureCloud → Integrations → Datadog → Edit Connection**.
{% endhint %}
{% endstep %}

{% step %}

#### Generate an Application Key

In **Organisation Settings → Application Keys → New Key**, create an application key named `SureCloud CCM` using the service account created in step 1. Copy the key value.

Application Keys inherit the permissions of the user who created them. Since the service account has the Read Only role, all API calls made with this key pair are restricted to read operations.
{% endstep %}

{% step %}

#### Identify your Datadog site

Datadog uses region-specific API base URLs. Identify the site your organisation uses:

| Datadog site  | API base URL                    |
| ------------- | ------------------------------- |
| US1 (default) | `https://api.datadoghq.com`     |
| US3           | `https://api.us3.datadoghq.com` |
| US5           | `https://api.us5.datadoghq.com` |
| EU1           | `https://api.datadoghq.eu`      |
| AP1           | `https://api.ap1.datadoghq.com` |

Your site is visible in the URL you use to log in to the Datadog console.
{% endstep %}

{% step %}

#### Enter credentials in SureCloud

In SureCloud, navigate to **Integrations → Datadog → Connect** and provide:

* **API Key**
* **Application Key**
* **Datadog site** (select from the list above)

Click **Test Connection**, then **Save**.
{% endstep %}
{% endstepper %}

## Endpoints

| API Call                            | Use Case                                                                                       |
| ----------------------------------- | ---------------------------------------------------------------------------------------------- |
| `GET /api/v1/monitor`               | Enumerate all monitors; identify disabled monitors covering security-relevant alert conditions |
| `GET /api/v1/monitor/{monitor_id}`  | Retrieve full monitor configuration including thresholds, notification targets, and state      |
| `GET /api/v1/logs/indexes`          | List log indexes and their retention periods and daily quota settings                          |
| `GET /api/v1/logs/config/pipelines` | Read log processing pipeline configuration                                                     |
| `GET /api/v2/audit/events`          | Collect Datadog audit trail events for administrative and access activity                      |
| `GET /api/v1/user`                  | Enumerate users in the Datadog organisation; detect inactive accounts                          |
| `GET /api/v2/users`                 | Read user roles and permission sets                                                            |
| `GET /api/v2/roles`                 | List all roles and their associated permissions                                                |
| `GET /api/v1/downtime`              | Read scheduled monitor downtimes; detect monitors silenced for extended periods                |
| `GET /api/v2/logs/config/archives`  | Read log archive configuration and destination settings                                        |

## Pagination

Datadog API list endpoints use cursor-based pagination via a `meta.page.after` cursor value. SureCloud passes the cursor as the `page[cursor]` query parameter in successive requests until no cursor is returned.

```json
{
  "data": [
    { "id": "abc-123", "type": "monitors", "attributes": { "name": "High error rate alert", ... } }
  ],
  "meta": {
    "page": {
      "after": "eyJzdGFydEF0IjoiMjAyNS0wNi0wMVQwMDowMDowMFoifQ=="
    }
  }
}
```

For v1 endpoints (such as `/api/v1/monitor`), pagination uses `page` and `page_size` query parameters. SureCloud increments the page number until fewer results than `page_size` are returned.

## Required permissions

SureCloud requires a user with the **Datadog Read Only** role (or equivalent custom role) to generate the Application Key. The Read Only role grants access to all read endpoints used by SureCloud without any write or configuration permissions.

The API Key and Application Key must both be from the same Datadog organisation. Cross-organisation access requires a separate connection per organisation.

## Polling frequency

| Data type                           | Collection interval |
| ----------------------------------- | ------------------- |
| Monitor configuration and state     | 24 hours            |
| Log index and archive configuration | 24 hours            |
| Audit trail events                  | 1 hour              |
| User and role inventory             | 24 hours            |
| Scheduled downtimes                 | 24 hours            |

## Troubleshooting

<details>

<summary>Test Connection fails with "403 Forbidden"</summary>

The API Key or Application Key is invalid, or the Application Key was generated by a user who has since been deactivated.

1. In **Datadog → Organisation Settings → API Keys**, confirm the `SureCloud CCM` key is active.
2. In **Organisation Settings → Application Keys**, confirm the `SureCloud CCM` application key is listed and the owning user account is active.
3. If either key has been deactivated or deleted, generate new keys following the setup steps and update them in **SureCloud → Integrations → Datadog → Edit Connection**.

</details>

<details>

<summary>Audit trail events are not appearing</summary>

The Datadog Audit Trail feature must be enabled at the organisation level before events are collected. In **Organisation Settings → Security → Audit Trail**, confirm that audit trail is enabled.

Audit Trail is available on Datadog Enterprise plans. If the toggle is not visible, your Datadog plan may not include this feature.

</details>

<details>

<summary>Monitors from some sub-organisations are missing</summary>

Datadog organisations with multi-organisation (parent/child) configurations require a separate API and Application Key pair per child organisation. SureCloud does not automatically traverse child organisations from a parent organisation connection.

Add each child organisation as a separate connection in **SureCloud → Integrations → Datadog → Add Connection**, providing the credentials specific to each child org.

</details>

<details>

<summary>Log index retention periods are not appearing</summary>

Log index configuration is read via `/api/v1/logs/indexes`. If retention data is missing, confirm the Application Key's owning user has the Read Only role — custom roles with restricted permissions may not include log configuration access.

In Datadog, navigate to **Logs → Configuration → Indexes** to verify log indexes are configured. If no indexes exist, the endpoint will return an empty list.

</details>

<a href="https://docs.datadoghq.com/api/latest/" class="button secondary">Datadog API reference</a> <a href="https://docs.datadoghq.com/account_management/audit_trail/" class="button secondary">Datadog Audit Trail documentation</a>


---

# 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/datadog.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.