Connect Datadog

Agent markdown

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

Create a Service Access Token (recommended) (Connection admin/user)

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)

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

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

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

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

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

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

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

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