Improve 401 Unauthorized error message with permission guidance

[shihanpan]

- Clarify that 401 errors can be due to invalid/expired API token OR insufficient permissions
- Add direct link to Workato API client management documentation
- Restructure error message to show both possible causes and resolution steps
- Improve actionability of error message for users debugging auth issues

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

[github-actions]

Coverage Report

File	Stmts	Miss	Cover	Missing
__init__.py	68	4	94%	10–11, 69–70
cli
__init__.py	52	3	94%	49, 51, 60
containers.py	27	0	100%
cli/commands
__init__.py	0	0	100%
api_clients.py	291	9	96%	27, 302, 448–449, 483, 493, 584, 615, 623
api_collections.py	257	3	98%	28, 183, 347
assets.py	47	2	95%	57–58
connections.py	526	5	99%	591, 593, 599, 637, 988
data_tables.py	165	5	96%	31, 253, 267, 321–322
guide.py	166	1	99%	106
init.py	107	0	100%
profiles.py	231	0	100%
properties.py	97	1	98%	21
pull.py	172	2	98%	193–194
workspace.py	39	2	94%	61, 71
cli/commands/connectors
__init__.py	0	0	100%
command.py	90	2	97%	110, 159
connector_manager.py	203	4	98%	176, 292, 300–301
cli/commands/projects
__init__.py	0	0	100%
command.py	272	10	96%	359–362, 373, 439–441, 491, 495
project_manager.py	166	7	95%	48, 66, 263–264, 276, 317, 325
cli/commands/push
__init__.py	0	0	100%
command.py	133	4	96%	109, 112, 230, 308
cli/commands/recipes
__init__.py	0	0	100%
command.py	427	9	97%	117, 133–134, 272–275, 403, 709
validator.py	706	20	97%	174, 883, 1136, 1223, 1246, 1279, 1281–1282, 1359–1361, 1457–1458, 1517–1518, 1707–1708, 1736–1738
cli/utils
__init__.py	4	0	100%
exception_handler.py	345	33	90%	134–135, 140–141, 143–144, 174–175, 181, 184–185, 270, 300, 333–337, 371, 398, 425, 482, 517, 576, 578–579, 584–585, 587–591
gitignore.py	14	0	100%
ignore_patterns.py	23	0	100%
spinner.py	43	0	100%
token_input.py	45	17	62%	70, 98, 100, 102–104, 107, 124, 127–128, 132–133, 136, 139–140, 142, 144
version_checker.py	135	6	95%	24, 26, 33–34, 72, 102
cli/utils/config
__init__.py	5	0	100%
manager.py	531	33	93%	127, 138, 149, 157–159, 162, 165, 177, 227–228, 399, 417, 421, 424–427, 443, 464, 478, 491, 533, 623–624, 661, 875, 1018–1019, 1033–1034, 1090, 1149
models.py	33	0	100%
profiles.py	334	15	95%	99, 195–196, 199, 234–236, 261–263, 522, 530, 541–542, 546
workspace.py	68	0	100%
TOTAL	5822	197	96%

[cmworkato]

When an authentication error occurs during any CLI command execution, the error should provide a hint to the user which references the specific Workato API Client scope(s) which are missing.

The error should call out the specific missing permission(s) in the API Client so the user understands exactly which permission is missing and can efficiently remedy the issue in the Workato UI.

[shihanpan]

Tested; permissions required shown as part of the error message

[shihanpan]

https://docs.google.com/document/d/1zLGNDRDS1As3Sz00AHqefqSWBB7wZT6rWmmbG_HjU2Y/edit?usp=sharing this is the compiled permission matrix

[cmworkato]

@shihanpan The CLI reported an "Authentication Error" and eludes to the cause being an Invalid API Token, regardless of whether or not this is actually the case.

In cases where this is an "Authorization Error" due to API scopes, we should report that only.

The end state is that only a single error condition can occur and be reported (i.e. either your API Token is bad, or your API scopes are bad, not both).

[shihanpan]

Capturing offline discussion. Since the current API returns 401 for both authorization error (not enough permissions) and authentication errors (wrong/bad API keys), there isn't really a way to distinguish this in our error response. Would need to reach out to P&E for clarification and potential feature request