Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

[docs-scanner] Unclear relationship between sandbox:use PAT permission and granular account permissions

Open Beginner friendly
  • Is something wrong?
#26,225 0 comments 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
1/5
Estimated time
Under an hour
Newbie friendliness
88/100
Issue type
Documentation
Clarity
Clearly specified
Activity status
Active
Tech stack
docker
Domain
documentation

Research direction

Open content/manuals/ai/sandboxes-api/authentication.md and read the “Authenticate automation with a PAT” and “Resource access and permissions” sections. Clarify how the sandbox:use PAT scope relates to sandboxesCreate, sandboxesRead, and sandboxesDelete, including that both checks affect each request. Confirm the documentation explains how to diagnose permission failures.

Written by the indexing model from the issue text.

Description

File: content/manuals/ai/sandboxes-api/authentication.md

Issue

The authentication documentation describes two different permission concepts without explaining their relationship:

  1. PAT scope: "When creating the token, select the sandbox:use permission in your Docker account's personal access token settings."

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

Dominant language
Markdown
Stars
4.7k
Forks
8.5k
Avg merge
1d 18h
Merged PRs (30d)
127

Getting set up

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from docker/docs

All issues in docker/docs

Similar issues

More Documentation issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.