# Connect Datadog

Canonical URL: https://docs.fuse.init.inc/integrations/datadog/setup

Create a Datadog SAT or PAT and submit the token plus site to Init.



## Before you start [#before-you-start]

Datadog uses **customer bearer credentials**. Init accepts standalone Service Access Tokens (`ddsat_`) or Personal Access Tokens (`ddpat_`), not classic API key + application key pairs.

**Connection admin/user** creates the token in Datadog and submits it with the correct site. Prefer a **Service Access Token** on a service account for production automations so access is not tied to an individual user.

You need:

* Permission to create SATs (`service_account_write` or `org_app_keys_write`) or PATs for your user.
* Knowledge of which Datadog site hosts your organization (US1, US3, US5, EU1, AP1, AP2, UK1, or government sites).

## Configure the provider [#configure-the-provider]

### Create a Service Access Token (recommended) (**Connection admin/user**) [#create-a-service-access-token-recommended-connection-adminuser]

1. In Datadog, open **Organization Settings → Service Accounts** and select (or create) a service account.
2. Under **Access Tokens**, create a new token.
3. Choose an expiration and select only the scopes required for the Init actions you will run.
4. Copy the secret immediately; Datadog shows it once. The value starts with `ddsat_`.

### Create a Personal Access Token (alternative) [#create-a-personal-access-token-alternative]

1. Open **Personal Settings → Access Tokens** (or Organization Settings → Access Tokens).
2. Create a PAT with a required TTL and mandatory scopes.
3. Copy the secret once. The value starts with `ddpat_`.

### Confirm the site [#confirm-the-site]

Identify your site from the Datadog app URL or **My Preferences**, then map it to Init’s `site` enum (`us1`, `us3`, `us5`, `eu1`, `ap1`, `ap2`, `uk1`, `us1_fed`, `us2_fed`).

## Connect to Init [#connect-to-init]

**Connection admin/user** starts a Datadog Connect session and submits:

| Field          | Required | Notes                                             |
| -------------- | -------- | ------------------------------------------------- |
| `access_token` | Yes      | Must start with `ddsat_` or `ddpat_`.             |
| `site`         | Yes      | Datadog site code matching your org’s data plane. |

Do not submit classic `DD-API-KEY` / `DD-APPLICATION-KEY` pairs; the Connect contract rejects them.

## Permissions [#permissions]

SAT/PAT scopes are mandatory and should match the generated action requirements. Prefer service-account SATs for shared connections so revocation is independent of employee offboarding.

A token created on one Datadog site is not valid on another. Choosing the wrong `site` sends requests to the wrong API origin.

## Monitor retirement workflow [#monitor-retirement-workflow]

Use `monitors.can_delete` before `monitors.delete` to learn whether a monitor is blocked by composites, downtimes, or other references. The preflight is **advisory only** (time-of-check/time-of-use): references can change between the check and the delete, so a later delete may still fail.

`monitors.delete` never sends Datadog’s `force` parameter. Resolve blockers first rather than forcing deletion.

`monitors.list` paginates with Datadog’s documented `page` and `page_size` query parameters. Init returns an opaque versioned page cursor (`p:N`). Pass that `cursor` from a previous response to continue. **Cursors issued before this versioned format cannot be resumed** — omit `cursor` once to restart pagination from page 0. An exact-full final page may require one additional empty request.

## Verify the connection [#verify-the-connection]

1. Complete Connect and confirm the connection is active.
2. Run Init’s connection test or a safe read such as listing users or monitors allowed by the token scopes.
3. Success looks like Datadog accepting the bearer token on the selected site without `401`/`403`.

Allow a few seconds after token creation for Datadog’s eventual consistency before treating failures as permanent.

## Rotate or revoke access [#rotate-or-revoke-access]

1. Create a new SAT or PAT with the same least-privilege scopes.
2. Reconnect in Init with the new `access_token` and the same `site`.
3. Revoke the previous token in Datadog (service account panel or Access Tokens).

If a token is exposed, revoke it immediately, then reconnect.

## Troubleshooting [#troubleshooting]

| Symptom                       | What to check                                                                             |
| ----------------------------- | ----------------------------------------------------------------------------------------- |
| Connect rejects the token     | Value must start with `ddsat_` or `ddpat_`; classic app keys are not accepted.            |
| `401` / `403`                 | Wrong site, revoked token, or missing scopes; wait briefly if the token was just created. |
| Works in UI but fails in Init | Confirm `site` matches the org’s Datadog site parameter.                                  |
| PAT expired                   | PATs require a TTL; create a new token and reconnect.                                     |
| User left the company         | Prefer SATs; rotate off user-owned PATs.                                                  |