File: content/manuals/ai/sandboxes-api/authentication.md
Issue
The authentication documentation describes two different permission concepts without explaining their relationship:
-
PAT scope: "When creating the token, select the sandbox:use permission in your Docker account's personal access token settings."
-
Account permissions: "Each request also checks whether you have permission for the action on the target resource. For example, creating a sandbox requires sandboxesCreate, reading it requires sandboxesRead, and deleting it requires sandboxesDelete."
The document never clarifies:
- Does the
sandbox:use PAT scope grant all the granular permissions (sandboxesCreate, sandboxesRead, etc.)?
- Are the granular permissions separate account-level settings that must also be configured?
- If a PAT has
sandbox:use but the account lacks sandboxesCreate, what happens?
Why this matters
A reader setting up authentication needs to know:
- Whether selecting
sandbox:use is sufficient for all sandbox operations
- Whether additional account configuration is required beyond creating the PAT
- How to diagnose permission errors (is it the PAT scope or the account permission?)
The current text suggests these are related but doesn't explain the relationship, leaving readers uncertain whether they've completed the setup correctly.
Suggested fix
Add a clarifying sentence in the "Authenticate automation with a PAT" section:
When creating the token, select the sandbox:use permission in your Docker account's personal access token settings. This scope grants access to all sandbox operations, subject to your account's permissions. The API checks both the PAT scope and your account permissions for each request.
Or add a subsection under "Resource access and permissions" that explicitly states:
The sandbox:use PAT scope authorizes your application to act on your behalf. Your account's permissions (sandboxesCreate, sandboxesRead, etc.) then determine which operations succeed. Both the PAT scope and the account permission must allow the action.
Found by nightly documentation quality scanner
File:
content/manuals/ai/sandboxes-api/authentication.mdIssue
The authentication documentation describes two different permission concepts without explaining their relationship:
PAT scope: "When creating the token, select the
sandbox:usepermission in your Docker account's personal access token settings."Account permissions: "Each request also checks whether you have permission for the action on the target resource. For example, creating a sandbox requires
sandboxesCreate, reading it requiressandboxesRead, and deleting it requiressandboxesDelete."The document never clarifies:
sandbox:usePAT scope grant all the granular permissions (sandboxesCreate,sandboxesRead, etc.)?sandbox:usebut the account lackssandboxesCreate, what happens?Why this matters
A reader setting up authentication needs to know:
sandbox:useis sufficient for all sandbox operationsThe current text suggests these are related but doesn't explain the relationship, leaving readers uncertain whether they've completed the setup correctly.
Suggested fix
Add a clarifying sentence in the "Authenticate automation with a PAT" section:
Or add a subsection under "Resource access and permissions" that explicitly states:
Found by nightly documentation quality scanner