[CRED-2815] Document PAT/SAT scope, TTL, and app-key restrictions - #39105
[CRED-2815] Document PAT/SAT scope, TTL, and app-key restrictions#39105emubello wants to merge 1 commit into
Conversation
Preview links (active after the
|
evazorro
left a comment
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
| 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. |
There was a problem hiding this comment.
| 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. |
There was a problem hiding this comment.
| - **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. |
There was a problem hiding this comment.
| - **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 |
There was a problem hiding this comment.
| ## 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 |
There was a problem hiding this comment.
| ## 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: |
There was a problem hiding this comment.
| 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: |
There was a problem hiding this comment.
| 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
|
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? |
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:
Calls that violate these restrictions return a
403 Forbiddenresponse.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 --checkvale hugo/content/en/account_management/personal-access-tokens.md hugo/content/en/account_management/service-access-tokens.mdVale reports no errors. Remaining warnings/suggestions are pre-existing lines in these files.