From 3d52c4c684a0d31d46374afe3ee9b761e1b6ce55 Mon Sep 17 00:00:00 2001 From: michael-richey Date: Fri, 17 Jul 2026 12:14:00 -0400 Subject: [PATCH] docs(users): document --use-v1-user-api Add a README section and table-of-contents entry describing the opt-in v1 user creation path (which preserves handles when users share an email). Co-Authored-By: Claude Opus 4.8 --- README.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/README.md b/README.md index 6f63cf0e..28872f6f 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ Datadog cli tool to sync resources across organizations. - [Config file](#config-file) - [Cleanup flag](#cleanup-flag) - [Verify DDR Status Flag](#verify-ddr-status-flag) + - [Create users via the v1 API](#create-users-via-the-v1-api) - [State Files](#state-files) - [Supported resources](#supported-resources) - [Best practices](#best-practices) @@ -210,6 +211,13 @@ For example, `ResourceA` and `ResourceB` are imported and synced, followed by de By default all commands check the Datadog Disaster Recovery (DDR) status of both the source and destination organizations before running. This behavior is controlled by the boolean flag `--verify-ddr-status` or the environment variable `DD_VERIFY_DDR_STATUS`. +#### Create users via the v1 API + +The destination enforces user uniqueness on the `handle`, not the email — multiple users may share an email address. The v2 user create endpoint (`POST /api/v2/users`) does not accept a `handle` (it derives one from the email), so users that share an email collapse onto a single handle: the first create takes a handle that may belong to another user, and later creates for that email return an HTTP 409. + +Passing `--use-v1-user-api` (or setting `DD_USE_V1_USER_API=true`) makes `sync` create users via the v1 user endpoint (`POST /api/v1/user`), which accepts an explicit handle, so every user keeps its own handle and no create collides. The flag is off by default. + + #### Running behind an HTTP proxy By default the tool's HTTP client ignores the environment and talks to Datadog directly. To run it behind a proxy, set `--http-client-trust-env true` (or the environment variable `DD_HTTP_CLIENT_TRUST_ENV=true`). When enabled, the underlying HTTP client honors the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables, as well as credentials from `.netrc`. This option is off by default. Note that when enabled, the configured proxy can observe all Datadog API traffic — including the `DD-API-KEY`, `DD-APPLICATION-KEY`, or JWT headers if it terminates TLS — and `.netrc` credentials may be automatically attached for matching hosts, so only enable this for a proxy you trust.