Skip to content

[CRED-2815] Document PAT/SAT scope, TTL, and app-key restrictions - #39105

Open
emubello wants to merge 1 commit into
masterfrom
emu/cred-2815/reopen-pat-sat-restrictions
Open

[CRED-2815] Document PAT/SAT scope, TTL, and app-key restrictions#39105
emubello wants to merge 1 commit into
masterfrom
emu/cred-2815/reopen-pat-sat-restrictions

Conversation

@emubello

Copy link
Copy Markdown

What changed

Adds a Restrictions section to the Personal Access Tokens and Service Access Tokens documentation.

The new sections document containment rules for API calls authenticated with a PAT or SAT:

  • Cannot create or update application keys. Revocation is still allowed.
  • Cannot create or update another token with scopes broader than its own.
  • Cannot create a token with a TTL that outlives itself.

Calls that violate these restrictions return a 403 Forbidden response.

Why

This redoes the changes from #38945 on a fresh branch after the docs repo reorg. The content now targets the current hugo/content/... paths.

Validation

  • git diff --check
  • vale hugo/content/en/account_management/personal-access-tokens.md hugo/content/en/account_management/service-access-tokens.md

Vale reports no errors. Remaining warnings/suggestions are pre-existing lines in these files.

@github-actions

Copy link
Copy Markdown
Contributor

@emubello
emubello marked this pull request as ready for review August 11, 2026 17:51
@emubello
emubello requested a review from a team as a code owner August 11, 2026 17:51
@jhgilbert jhgilbert added the astro-reorg-no-conflicts Needs manual conflict resolution after replatforming reorg label Aug 11, 2026

@evazorro evazorro left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A PAT can create a SAT, but can a SAT create a PAT? If not, could be worth mentioning as a restriction in the list

- **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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
A call that violates one of these restrictions returns a `403 Forbidden` response.

The first sentence duplicates your intro sentence here, so I don't think you need it

- **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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.
A call that violates one of these restrictions returns a `403 Forbidden` response.

Same reasoning here


- **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 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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Time-to-live (TTL) on new tokens**: A PAT cannot create a PAT or a SAT with a TTL that outlives itself.
- **Time-to-live (TTL) on new tokens**: A PAT cannot create a PAT or a SAT with a TTL that extends beyond its own expiration.

"itself" was a little unclear, rephrasing to clarify


- **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 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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **Time-to-live (TTL) on new tokens**: A SAT cannot create a SAT with a TTL that outlives itself.
- **Time-to-live (TTL) on new tokens**: A SAT cannot create a SAT with a TTL that extends beyond its own expiration.


**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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Restrictions
## Restrictions on PAT-authenticated API calls

Makes the header clearer in case this section is retrieved in isolation (like by an AI agent)

**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

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
## Restrictions
## Restrictions on SAT-authenticated API calls


## Restrictions

To limit how a SAT can escalate its own access, Datadog restricts what an API call authenticated with a SAT can do. These restrictions apply regardless of the API client making the call:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
To limit how a SAT can escalate its own access, Datadog restricts what an API call authenticated with a SAT can do. These restrictions apply regardless of the API client making the call:
To prevent privilege escalation, Datadog restricts what an API call authenticated with a SAT can do. These restrictions apply regardless of the API client making the call:

Avoids personifying the SAT


## 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:

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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:
To prevent privilege escalation, Datadog restricts what an API call authenticated with a PAT can do. These restrictions apply regardless of the API client making the call:

Same here

@emubello

Copy link
Copy Markdown
Author

Hi @evazorro a SAT cannot create a PAT, since it will be owned by a service account, thus making it a SAT as well. Do you think I should call out this distinction?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

astro-reorg-no-conflicts Needs manual conflict resolution after replatforming reorg

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants