From 7255546161e4c98d1d7255bb01a22a3cac0a946e Mon Sep 17 00:00:00 2001 From: "emu.eghrebello" Date: Mon, 20 Jul 2026 14:17:55 -0400 Subject: [PATCH 1/2] [CRED-2815] Document PAT/SAT scope, TTL, and app-key restrictions Add a Restrictions section to the Personal Access Tokens and Service Access Tokens pages describing the new containment rules: PATs/SATs cannot create or update application keys, cannot mint or update another PAT/SAT with broader scopes than their own, and cannot create a PAT/SAT with a longer TTL than their own. --- .../en/account_management/personal-access-tokens.md | 10 ++++++++++ content/en/account_management/service-access-tokens.md | 10 ++++++++++ 2 files changed, 20 insertions(+) diff --git a/content/en/account_management/personal-access-tokens.md b/content/en/account_management/personal-access-tokens.md index a2cd38021b0..519ac4add8e 100644 --- a/content/en/account_management/personal-access-tokens.md +++ b/content/en/account_management/personal-access-tokens.md @@ -66,6 +66,16 @@ curl -X GET "https://api.datadoghq.com/api/v2/users" \ **Note:** When a valid PAT is provided in the `dd-application-key` header, Datadog authenticates with the PAT only. The `dd-api-key` header is optional and its value is not evaluated. +## Restrictions + +To limit how a PAT can escalate its own access, Datadog restricts what an API call authenticated with a PAT can do. These restrictions apply regardless of the API client making the call: + +- **Application keys**: A PAT cannot create or update application keys. Revoking application keys is still allowed. +- **Scopes on new tokens**: A PAT can create or update another PAT or a SAT only if the new token's scopes are a subset of its own scopes. +- **Time-to-live (TTL) on new tokens**: A PAT cannot create a PAT or a SAT with a TTL that outlives itself. + +These restrictions apply only to API calls authenticated with a PAT or SAT. A call that violates one of these restrictions returns a `403 Forbidden` response. + ## Manage Personal Access Tokens ### View your tokens diff --git a/content/en/account_management/service-access-tokens.md b/content/en/account_management/service-access-tokens.md index 39d82be8d32..5fd3007ccef 100644 --- a/content/en/account_management/service-access-tokens.md +++ b/content/en/account_management/service-access-tokens.md @@ -91,6 +91,16 @@ curl -X GET "https://api.datadoghq.com/api/v2/users" \ **Note:** When a valid SAT is provided in the `dd-application-key` header, Datadog authenticates with the SAT only. The `dd-api-key` header is optional and its value is not evaluated. +## Restrictions + +To limit how a SAT can escalate its own access, Datadog restricts what an API call authenticated with a SAT can do, regardless of the API client making the call: + +- **Application keys**: A SAT cannot create or update application keys. Revoking application keys is still allowed. +- **Scopes on new tokens**: A SAT can create or update another SAT or a PAT only if the new token's scopes are a subset of its own scopes. +- **Time-to-live (TTL) on new tokens**: A SAT cannot create a SAT or a PAT with a TTL that outlives itself. + +These restrictions apply only to API calls authenticated with a PAT or SAT. A call that violates one of these restrictions returns a `403 Forbidden` response. + ## Manage Service Access Tokens ### View tokens From 0f94a017ca9f5a9a6239d42b87e6000ceb4460d6 Mon Sep 17 00:00:00 2001 From: "emu.eghrebello" Date: Tue, 21 Jul 2026 11:00:49 -0400 Subject: [PATCH 2/2] [CRED-2815] Clarify PAT/SAT token creation restrictions A SAT cannot create a PAT, since PAT creation is always scoped to the authenticated caller. Remove that language from the SAT restrictions section. --- content/en/account_management/personal-access-tokens.md | 2 +- content/en/account_management/service-access-tokens.md | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/content/en/account_management/personal-access-tokens.md b/content/en/account_management/personal-access-tokens.md index 519ac4add8e..ba4d38150f2 100644 --- a/content/en/account_management/personal-access-tokens.md +++ b/content/en/account_management/personal-access-tokens.md @@ -71,7 +71,7 @@ curl -X GET "https://api.datadoghq.com/api/v2/users" \ To limit how a PAT can escalate its own access, Datadog restricts what an API call authenticated with a PAT can do. These restrictions apply regardless of the API client making the call: - **Application keys**: A PAT cannot create or update application keys. Revoking application keys is still allowed. -- **Scopes on new tokens**: A PAT can create or update another PAT or a SAT only if the new token's scopes are a subset of its own scopes. +- **Scopes on new tokens**: A PAT can create or update a PAT or a SAT only if the new token's scopes are a subset of its own scopes. - **Time-to-live (TTL) on new tokens**: A PAT cannot create a PAT or a SAT with a TTL that outlives itself. These restrictions apply only to API calls authenticated with a PAT or SAT. A call that violates one of these restrictions returns a `403 Forbidden` response. diff --git a/content/en/account_management/service-access-tokens.md b/content/en/account_management/service-access-tokens.md index 5fd3007ccef..2d634b8bd42 100644 --- a/content/en/account_management/service-access-tokens.md +++ b/content/en/account_management/service-access-tokens.md @@ -96,8 +96,8 @@ with the SAT only. The `dd-api-key` header is optional and its value is not eval To limit how a SAT can escalate its own access, Datadog restricts what an API call authenticated with a SAT can do, regardless of the API client making the call: - **Application keys**: A SAT cannot create or update application keys. Revoking application keys is still allowed. -- **Scopes on new tokens**: A SAT can create or update another SAT or a PAT only if the new token's scopes are a subset of its own scopes. -- **Time-to-live (TTL) on new tokens**: A SAT cannot create a SAT or a PAT with a TTL that outlives itself. +- **Scopes on new tokens**: A SAT can create or update another SAT only if the new token's scopes are a subset of its own scopes. +- **Time-to-live (TTL) on new tokens**: A SAT cannot create a SAT with a TTL that outlives itself. These restrictions apply only to API calls authenticated with a PAT or SAT. A call that violates one of these restrictions returns a `403 Forbidden` response.