Ask for the narrowest scope that makes the example work, and say what it allows. Telling readers to create a full access or admin token because it is quicker teaches over-broad credentials, and those tokens often end up in scripts, chat messages and repositories. Least privilege starts on the docs page.
The shortcut and its cost
A tutorial needs a token. The author picks the highest permission because it never fails, and the steps stay short. The reader follows along, then reuses that token in their real script. A leaked broad token is far more damaging than a leaked read-only one.
A good docs page makes the safe choice the easy one.
How to choose the scope for an example
- List the exact API calls your example makes.
- Map each call to the permission it needs, using the product's own permission reference.
- Choose the smallest set that covers them. Read-only where the example only reads.
- Test the example with that token alone, and confirm it fails when you remove a scope.
- Document the result in the example, not in a separate reference page.
- Recommend an expiry date for the token where the product supports one.
| Example does | Ask for |
|---|---|
| Lists resources | Read-only permission on that resource type |
| Creates one kind of resource | Write permission on that type only |
| Deletes resources | A separate, explicitly named delete permission, and a warning |
| Manages users or billing | Do not use it in a tutorial; link to a dedicated admin guide |
Wording that works
State the scope in the step that creates the token:
"Create a token with read access to projects only. Do not give it write or admin rights. You will use it in the next step."
Then add a line about handling: store it in an environment variable, never in source, and revoke it when you finish the tutorial. For code examples, see how should docs show api keys in code samples.
Support the safe path in the product
Docs can only do so much if the product makes narrow tokens hard to create. If you own both, raise it with the product team: scoped tokens, short default expiry, and a clear permission list all make the docs simpler. Where a token cannot be narrowed, say so honestly and describe compensating steps such as a dedicated test account.
What reviewers should check
In a docs pull request, search for words like admin, owner, full access and all permissions. Each hit needs a reason. If the reason is "it is shorter", rewrite it. See also security acceptance criteria for an API endpoint examples.
Try it yourself
API scanning shows what an endpoint exposes to a token. Click through one.
Click through it at your own pace, or open it full screen.
Safeguard includes API security scanning and policy gates, and agent identity for governing what automated actors may do. The free scan is at https://gold.safeguard.sh/scan.
Quick check
Is an admin token acceptable in a short tutorial?
It is convenient, but readers reuse it. Ask for the narrowest scope and test the example with it.
Should tutorial tokens expire?
Where the product allows it, yes. Tell readers to revoke the token when they finish.
Last reviewed: 19 October 2026.
