From 4400ee954b00a7de70a6697bc68a6bedc4ae072a Mon Sep 17 00:00:00 2001
From: Jacob Goren <jacob@scarcebytes.com>
Date: Tue, 30 Sep 2025 10:41:04 -0700
Subject: [PATCH 1/3] Add comprehensive API token permissions documentation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Created PERMISSIONS.md with detailed documentation of all available
API token scopes and their corresponding CLI commands. Includes:

- Quick start table with standard development permissions
- Complete permission reference organized by scope category
- Mapping of each permission to CLI commands that use them
- Recommended permission sets for different use cases
- Common CLI workflows with required permissions
- Troubleshooting guide for permission errors

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/PERMISSIONS.md | 531 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 531 insertions(+)
 create mode 100644 docs/PERMISSIONS.md

diff --git a/docs/PERMISSIONS.md b/docs/PERMISSIONS.md
new file mode 100644
index 0000000..826c1ed
--- /dev/null
+++ b/docs/PERMISSIONS.md
@@ -0,0 +1,531 @@
+# API Token Permissions
+
+This document describes the permissions (scopes) available for Workato API tokens and which CLI commands require which permissions.
+
+## Quick Start: Standard Development Permissions
+
+For typical recipe development workflow, grant these permissions when creating your API client:
+
+| Scope Category | Permissions Required |
+|----------------|---------------------|
+| **Workspace Details** | Get details (`GET /api/users/me`) |
+| **Projects & Folders** | List projects (`GET /api/projects`)<br>List folders (`GET /api/folders`)<br>Create project or folder (`POST /api/folders`) |
+| **Recipes** | List (`GET /api/recipes`)<br>Get details (`GET /api/recipes/:id`)<br>Create (`POST /api/recipes`)<br>Update (`PUT /api/recipes/:id`)<br>Start (`PUT /api/recipes/:id/start`)<br>Stop (`PUT /api/recipes/:id/stop`)<br>Update connection for recipe (`PUT /api/recipes/:recipe_id/connect`) |
+| **Connections** | List (`GET /api/connections`)<br>Create (`POST /api/connections`)<br>Update (`POST /api/connections/:id`)<br>Get picklist values (`POST /api/connections/:id/pick_list`) |
+| **Recipe Lifecycle Management** | Get package details (`GET /api/packages/:id`)<br>Download package (`GET /api/packages/:id/download`)<br>Export package (`POST /api/packages/export/:id`)<br>Import package (`POST /api/packages/import/:id`) |
+| **Export Manifests** | Create export manifest (`POST /api/export_manifests`)<br>Show export manifest (`GET /api/export_manifests/:id`)<br>Get folder assets (`GET /api/export_manifests/folder_assets`) |
+
+**Use case:** This permission set enables all core CLI workflows including `workato init`, `workato pull`, `workato push`, `workato recipes start/stop`, and `workato connections create`.
+
+---
+
+## Overview
+
+Workato API tokens use a scope-based permission system. When creating an API client in **Workspace Admin → API clients**, you can select which scopes to grant. The Workato CLI inherits these permissions from your API token.
+
+## Permission Scopes
+
+### Project Assets
+Define access to core recipe building features within projects.
+
+#### Projects & Folders (7/7)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List projects | `GET` | `/api/projects` | `workato projects list` |
+| List folders | `GET` | `/api/folders` | `workato projects list` (recursive) |
+| Create project or folder | `POST` | `/api/folders` | `workato init` |
+| Delete folder | `DELETE` | `/api/folders/:id` | - |
+| Update folder | `PUT` | `/api/folders/:id` | - |
+| Delete project | `DELETE` | `/api/projects/:id` | - |
+| Update project | `PUT` | `/api/projects/:id` | - |
+
+#### Connections (5/6)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List | `GET` | `/api/connections` | `workato connections list` |
+| Create | `POST` | `/api/connections` | `workato connections create` |
+| Update | `POST` | `/api/connections/:id` | `workato connections update` |
+| Delete Connection | `DELETE` | `/api/connections/:id` | `workato connections delete` |
+| Disconnect Connection | `POST` | `/api/connections/:id/disconnect` | - |
+| Get picklist values | `POST` | `/api/connections/:id/pick_list` | `workato connections picklist` |
+
+#### Recipes (12/12)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List | `GET` | `/api/recipes` | `workato recipes list` |
+| Get job counts for recipes | `GET` | `/api/recipes/job_counts` | - |
+| Get details | `GET` | `/api/recipes/:id` | - |
+| Create | `POST` | `/api/recipes` | `workato push` |
+| Update | `PUT` | `/api/recipes/:id` | `workato push` |
+| Copy | `POST` | `/api/recipes/:id/copy` | - |
+| Delete | `DELETE` | `/api/recipes/:id` | - |
+| Start | `PUT` | `/api/recipes/:id/start` | `workato recipes start` |
+| Stop | `PUT` | `/api/recipes/:id/stop` | `workato recipes stop` |
+| Forces a running recipe to poll immediately | `POST` | `/api/recipes/:recipe_id/poll_now` | - |
+| Reset recipe trigger | `POST` | `/api/recipes/:recipe_id/reset_trigger` | - |
+| Update connection for recipe | `PUT` | `/api/recipes/:recipe_id/connect` | `workato recipes update-connection` |
+
+#### Genies (13/13)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List genies | `GET` | `/api/agentic/genies` | - |
+| Get genie | `GET` | `/api/agentic/genies/:id` | - |
+| Create genie | `POST` | `/api/agentic/genies` | - |
+| Update genie | `PUT` | `/api/agentic/genies/:id` | - |
+| Delete genie | `DELETE` | `/api/agentic/genies/:id` | - |
+| Start genie | `POST` | `/api/agentic/genies/:id/start` | - |
+| Stop genie | `POST` | `/api/agentic/genies/:id/stop` | - |
+| Assign skills to genie | `POST` | `/api/agentic/genies/:id/assign_skills` | - |
+| Remove skills from genie | `POST` | `/api/agentic/genies/:id/remove_skills` | - |
+| Assign knowledge bases to genie | `POST` | `/api/agentic/genies/:id/assign_knowledge_bases` | - |
+| Remove knowledge bases from genie | `POST` | `/api/agentic/genies/:id/remove_knowledge_bases` | - |
+| Assign user groups to genie | `POST` | `/api/agentic/genies/:id/assign_user_groups` | - |
+| Remove user groups from genie | `POST` | `/api/agentic/genies/:id/remove_user_groups` | - |
+
+#### Knowledge Bases (7/7)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List knowledge bases | `GET` | `/api/agentic/knowledge_bases` | - |
+| Get knowledge base | `GET` | `/api/agentic/knowledge_bases/:id` | - |
+| Create knowledge base | `POST` | `/api/agentic/knowledge_bases` | - |
+| Update knowledge base | `PUT` | `/api/agentic/knowledge_bases/:id` | - |
+| Delete knowledge base | `DELETE` | `/api/agentic/knowledge_bases/:id` | - |
+| Get knowledge base data sources | `GET` | `/api/agentic/knowledge_bases/:id/data_sources` | - |
+| Get knowledge base recipes | `GET` | `/api/agentic/knowledge_bases/:id/recipes` | - |
+
+#### Skills (3/3)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List skills | `GET` | `/api/agentic/skills` | - |
+| Get skill | `GET` | `/api/agentic/skills/:id` | - |
+| Create skill | `POST` | `/api/agentic/skills` | - |
+
+#### Recipe Versions (3/3)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List | `GET` | `/api/recipes/:recipe_id/versions` | - |
+| Get details | `GET` | `/api/recipes/:recipe_id/versions/:id` | - |
+| Update | `PUT` | `/api/recipes/:recipe_id/versions/:id` | - |
+
+#### Jobs (3/3)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List | `GET` | `/api/recipes/:recipe_id/jobs` | - |
+| Get job | `GET` | `/api/recipes/:recipe_id/jobs/:job_id` | - |
+| Resume suspended job | `POST` | `/api/job/resume` | - |
+
+#### Tag Assignments (1/1)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| Manage tag assignments | `POST` | `/api/tags_assignments` | - |
+
+#### Test Cases (3/3)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List test cases for recipe | `GET` | `/api/recipes/:recipe_id/test_cases` | - |
+| Run test cases | `POST` | `/api/test_cases/run_requests` | - |
+| Get run details | `GET` | `/api/test_cases/run_requests/:id` | - |
+
+---
+
+### Recipe Lifecycle Management
+Define access to assets transfer across workspaces.
+
+#### Recipe Lifecycle Management (4/4)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| Get package details | `GET` | `/api/packages/:id` | `workato pull`, `workato push` |
+| Download package | `GET` | `/api/packages/:id/download` | `workato pull` |
+| Export package | `POST` | `/api/packages/export/:id` | `workato pull` |
+| Import package | `POST` | `/api/packages/import/:id` | `workato push` |
+
+#### Export Manifests (5/5)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| Create export manifest | `POST` | `/api/export_manifests` | `workato pull` |
+| Show export manifest | `GET` | `/api/export_manifests/:id` | `workato pull` |
+| Update export manifest | `PUT` | `/api/export_manifests/:id` | - |
+| Delete export manifest | `DELETE` | `/api/export_manifests/:id` | - |
+| Get folder assets for export manifest | `GET` | `/api/export_manifests/folder_assets` | `workato pull` |
+
+---
+
+### Workspace Data
+Define access to data configured at the workspace-level.
+
+#### Lookup Tables (9/9)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List tables | `GET` | `/api/lookup_tables` | - |
+| Create table | `POST` | `/api/lookup_tables` | - |
+| List rows | `GET` | `/api/lookup_tables/:lookup_table_id/rows` | - |
+| Get row | `GET` | `/api/lookup_tables/:lookup_table_id/rows/:row_id` | - |
+| Lookup row | `GET` | `/api/lookup_tables/:lookup_table_id/lookup` | - |
+| Update row | `PUT` | `/api/lookup_tables/:lookup_table_id/rows/:row_id` | - |
+| Add row | `POST` | `/api/lookup_tables/:lookup_table_id/rows` | - |
+| Delete row | `DELETE` | `/api/lookup_tables/:lookup_table_id/rows/:row_id` | - |
+| Batch delete tables | `POST` | `/api/lookup_tables/batch_delete` | - |
+
+#### Data Tables (6/6)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List data tables | `GET` | `/api/data_tables` | `workato data-tables list` |
+| Create a data table | `POST` | `/api/data_tables` | `workato data-tables create` |
+| Get data table by id | `GET` | `/api/data_tables/:data_table_id` | - |
+| Delete a data table | `DELETE` | `/api/data_tables/:data_table_id` | `workato data-tables delete` |
+| Update a data table | `PUT` | `/api/data_tables/:data_table_id` | - |
+| Truncate a data table | `POST` | `/api/data_tables/:data_table_id/truncate` | `workato data-tables truncate` |
+
+#### Data Table Records (4/4)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| Create record | `POST` | `/api/v1/tables/:data_table_id/records` | - |
+| Update record | `PUT` | `/api/v1/tables/:data_table_id/records/:record_id` | - |
+| Delete record | `DELETE` | `/api/v1/tables/:data_table_id/records/:record_id` | - |
+| Query records | `POST` | `/api/v1/tables/:data_table_id/records/query` | - |
+
+#### Event Streams (2/2)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| Publish message to event topic | `POST` | `/api/v1/topics/:topic_id/publish` | - |
+| Read messages from event topic | `POST` | `/api/v1/topics/:topic_id/consume` | - |
+
+#### Event Streams Topics (6/6)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List topics | `GET` | `/api/event_streams/topics` | - |
+| Create a topic | `POST` | `/api/event_streams/topics` | - |
+| Get topic by id | `GET` | `/api/event_streams/topics/:topic_id` | - |
+| Delete a topic | `DELETE` | `/api/event_streams/topics/:topic_id` | - |
+| Update a topic | `PUT` | `/api/event_streams/topics/:topic_id` | - |
+| Purge a topic | `PUT` | `/api/event_streams/topics/:topic_id/purge` | - |
+
+#### Environment Properties (2/2)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List | `GET` | `/api/properties` | `workato properties list` |
+| Upsert | `POST` | `/api/properties` | `workato properties set` |
+
+---
+
+### API Platform
+Define access to manage and monitor API recipe endpoints and collections.
+
+#### Certificate Bundles (5/5)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List certificate bundles | `GET` | `/api/cert_bundles` | - |
+| Create certificate bundle | `POST` | `/api/cert_bundles` | - |
+| Update certificate bundle | `PUT` | `/api/cert_bundles/:cert_bundle_id` | - |
+| Delete certificate bundle | `DELETE` | `/api/cert_bundles/:cert_bundle_id` | - |
+| Download certificate bundle | `GET` | `/api/cert_bundles/:cert_bundle_id` | - |
+
+#### API Portal (1/1)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List API Portals | `GET` | `/api/v2/api_portals` | - |
+
+#### Collections & Endpoints (5/5)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List collections | `GET` | `/api/api_collections` | `workato api-collections list` |
+| Create collection | `POST` | `/api/api_collections` | `workato api-collections create` |
+| List endpoints in a collection | `GET` | `/api/api_endpoints` | `workato api-collections endpoints` |
+| Enable endpoint | `PUT` | `/api/api_endpoints/:api_endpoint_id/enable` | - |
+| Disable endpoint | `PUT` | `/api/api_endpoints/:api_endpoint_id/disable` | - |
+
+#### Clients & Access Profiles (12/12)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List clients | `GET` | `/api/api_clients`, `/api/v2/api_clients` | `workato api-clients list` |
+| Get client by ID | `GET` | `/api/v2/api_clients/:api_client_id` | - |
+| Create client | `POST` | `/api/api_clients`, `/api/v2/api_clients` | `workato api-clients create` |
+| Update client | `PUT` | `/api/v2/api_clients/:api_client_id` | - |
+| Delete client | `DELETE` | `/api/v2/api_clients/:api_client_id` | `workato api-clients delete` |
+| List access profiles | `GET` | `/api/api_access_profiles`, `/api/v2/api_clients/:api_client_id/api_keys` | - |
+| Update access profile | `PUT` | `/api/api_access_profiles/:api_access_profile_id`, `/api/v2/api_clients/:api_client_id/api_keys/:api_key_id` | - |
+| Create access profile | `POST` | `/api/api_access_profiles`, `/api/v2/api_clients/:api_client_id/api_keys` | - |
+| Enable access profile | `PUT` | `/api/api_access_profiles/:api_access_profile_id/enable`, `/api/v2/api_clients/:api_client_id/api_keys/:api_key_id/enable` | - |
+| Disable access profile | `PUT` | `/api/api_access_profiles/:api_access_profile_id/disable`, `/api/v2/api_clients/:api_client_id/api_keys/:api_key_id/disable` | - |
+| Refresh token/secret | `PUT` | `/api/api_access_profiles/:access_profile_id/refresh_secret`, `/api/v2/api_clients/:api_client_id/api_keys/:api_key_id/refresh_secret` | - |
+| Delete access profile | `DELETE` | `/api/v2/api_clients/:api_client_id/api_keys/:api_key_id` | - |
+
+---
+
+### Connector SDKs
+Define access to managing custom connectors and their versions.
+
+#### Connector SDKs (7/7)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List | `GET` | `/api/custom_connectors` | `workato connectors list` |
+| Release latest version | `POST` | `/api/custom_connectors/:id/release` | - |
+| Share latest version | `POST` | `/api/custom_connectors/:id/share` | - |
+| Update custom connector | `PUT` | `/api/custom_connectors/:id` | `workato connectors update` |
+| Create custom connector | `POST` | `/api/custom_connectors` | `workato connectors create` |
+| Search custom connectors | `GET` | `/api/custom_connectors/search` | - |
+| Get custom connector code | `GET` | `/api/custom_connectors/:id/code` | `workato connectors get-code` |
+
+#### SDK CLI (2/2)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| Generate Schema from CSV | `POST` | `/api/sdk/generate_schema/csv` | - |
+| Generate Schema from JSON | `POST` | `/api/sdk/generate_schema/json` | - |
+
+---
+
+### Custom OAuth Profiles
+Define access to manage custom OAuth profiles.
+
+#### Custom OAuth Profiles (5/5)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List custom OAuth profiles | `GET` | `/api/custom_oauth_profiles` | - |
+| Create custom OAuth profiles | `POST` | `/api/custom_oauth_profiles` | - |
+| Get custom OAuth profile | `GET` | `/api/custom_oauth_profiles/:id` | - |
+| Update custom OAuth profile | `PUT` | `/api/custom_oauth_profiles/:id` | - |
+| Delete custom OAuth profile | `DELETE` | `/api/custom_oauth_profiles/:id` | - |
+
+---
+
+### On-Prem Groups and Agents
+Define access to manage connectivity to authorized on-prem applications through groups and agents.
+
+#### On-Prem Groups (7/7)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List | `GET` | `/api/on_prem_groups` | - |
+| Get status | `GET` | `/api/on_prem_groups/:id/status` | - |
+| Get details | `GET` | `/api/on_prem_groups/:id` | - |
+| Update | `PUT` | `/api/on_prem_groups/:id` | - |
+| Create | `POST` | `/api/on_prem_groups` | - |
+| Delete | `DELETE` | `/api/on_prem_groups/:id` | - |
+| Get agents in group | `GET` | `/api/on_prem_groups/:id/agents` | - |
+
+#### On-Prem Agents (8/8)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List | `GET` | `/api/on_prem_agents` | - |
+| Search | `GET` | `/api/on_prem_agents/search` | - |
+| Get status | `GET` | `/api/on_prem_agents/:id/status` | - |
+| Get details | `GET` | `/api/on_prem_agents/:id` | - |
+| Update | `PUT` | `/api/on_prem_agents/:id` | - |
+| Create | `POST` | `/api/on_prem_agents` | - |
+| Delete | `DELETE` | `/api/on_prem_agents/:id` | - |
+| Get activation code | `GET` | `/api/on_prem_agents/:id/activation_code` | - |
+
+---
+
+### Partner Marketplace
+Define access to endpoints that help in the creation of a connector marketplace for your customers.
+
+#### Connectors (2/2)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| Search connectors | `GET` | `/api/integrations` | - |
+| List connectors | `GET` | `/api/integrations/all` | - |
+
+---
+
+### Workspace Collaborators
+Define access to manage collaborators and their roles in your workspace.
+
+#### Collaborators (6/6)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| Invite | `POST` | `/api/member_invitations` | - |
+| Get collaborators | `GET` | `/api/members` | - |
+| Get collaborator | `GET` | `/api/members/:id` | - |
+| Update collaborator's roles | `PUT` | `/api/members/:id` | - |
+| Get collaborator privileges | `GET` | `/api/members/:id/privileges` | - |
+| Delete collaborator | `DELETE` | `/api/members/:id` | - |
+
+#### Collaborator Roles (3/3)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List non-system roles | `GET` | `/api/roles` | - |
+| Copy non-system role | `POST` | `/api/roles/:id/copy` | - |
+| Update non-system role | `PUT` | `/api/roles/:id` | - |
+
+---
+
+### Workspace Details
+Define access to retrieval of workspace details.
+
+#### Workspace Details (1/1)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| Get details | `GET` | `/api/users/me` | `workato workspace`, `workato init` |
+
+---
+
+### Environment Management
+Define access to environment management operations.
+
+#### Secrets Management (1/1)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| Clear secrets cache | `POST` | `/api/secrets_management/clear_cache` | - |
+
+#### Audit Log (1/1)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| Get audit log | `GET` | `/api/activity_logs` | - |
+
+#### Tags (4/4)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List tags | `GET` | `/api/tags` | - |
+| Create tag | `POST` | `/api/tags` | - |
+| Update tag | `PUT` | `/api/tags/:handle` | - |
+| Delete tag | `DELETE` | `/api/tags/:handle` | - |
+
+---
+
+### Developer API Clients
+Define access to manage API clients.
+
+#### API Clients (6/6)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List API clients | `GET` | `/api/developer_api_clients` | - |
+| Create API clients | `POST` | `/api/developer_api_clients` | - |
+| Get API client by ID | `GET` | `/api/developer_api_clients/:id` | - |
+| Update API client | `PUT` | `/api/developer_api_clients/:id` | - |
+| Delete API client | `DELETE` | `/api/developer_api_clients/:id` | - |
+| Regenerate API client token | `POST` | `/api/developer_api_clients/:id/regenerate` | - |
+
+#### API Client Roles (2/2)
+
+| Permission | HTTP Method | Endpoint | CLI Commands |
+|------------|-------------|----------|--------------|
+| List API client roles | `GET` | `/api/developer_api_client_roles` | - |
+| Copy API client role | `POST` | `/api/developer_api_client_roles/:id/copy` | - |
+
+---
+
+## Recommended Permission Sets
+
+### Basic CLI Usage (Read-Only)
+For users who only need to view and list resources:
+- **Workspace Details**: Get details
+- **Projects & Folders**: List projects, List folders
+- **Recipes**: List, Get details
+- **Connections**: List
+- **Data Tables**: List data tables
+
+### Standard Development
+For typical recipe development workflow:
+- All permissions from **Basic CLI Usage**
+- **Projects & Folders**: Create project or folder
+- **Recipes**: Create, Update, Start, Stop, Update connection for recipe
+- **Connections**: Create, Update, Get picklist values
+- **Recipe Lifecycle Management**: All permissions
+- **Export Manifests**: All permissions
+
+### Full CLI Access
+For complete control over all CLI features:
+- **All permissions** across all scopes
+
+---
+
+## Common CLI Workflows
+
+### `workato init` - Initialize Project
+**Required permissions:**
+- Workspace Details → Get details
+- Projects & Folders → List projects, Create project or folder
+
+### `workato pull` - Pull Project Assets
+**Required permissions:**
+- Projects & Folders → List folders
+- Recipe Lifecycle Management → Create export manifest, Export package, Download package
+- Export Manifests → Create export manifest, Show export manifest, Get folder assets
+
+### `workato push` - Push Project Assets
+**Required permissions:**
+- Recipe Lifecycle Management → Import package, Get package details
+- Recipes → Create, Update
+
+### `workato recipes start/stop` - Manage Recipes
+**Required permissions:**
+- Recipes → List, Start, Stop
+
+### `workato connections create` - Create Connection
+**Required permissions:**
+- Connections → Create, Get picklist values
+
+---
+
+## Troubleshooting
+
+### 403 Forbidden Errors
+If you receive a `403 Forbidden` error, your API token lacks the required permissions:
+
+```
+❌ Access forbidden
+   You don't have permission to perform this action
+💡 Please check:
+   • Your account has the required permissions
+   • You're working in the correct workspace/folder
+   • The resource exists and is accessible to you
+```
+
+**Solution:** Check your API client's scopes in **Workspace Admin → API clients** and grant the necessary permissions.
+
+### 401 Unauthorized Errors
+If you receive a `401 Unauthorized` error, your API token is invalid or expired:
+
+```
+❌ Authentication failed
+   Your API token may be invalid
+💡 Please check your authentication:
+   • Verify your API token is correct
+   • Run 'workato profiles list' to check your profile
+   • Run 'workato profiles use' to update your credentials
+```
+
+**Solution:** Regenerate your API token or verify it's correctly stored in your profile.
+
+---
+
+## Related Documentation
+
+- [Quick Start Guide](QUICK_START.md)
+- [Command Reference](COMMAND_REFERENCE.md)
+- [Developer Guide](DEVELOPER_GUIDE.md)

From 1bc44985da6a3287a90b38e26bff18408a733fee Mon Sep 17 00:00:00 2001
From: Jacob Goren <jacob@scarcebytes.com>
Date: Tue, 30 Sep 2025 10:44:46 -0700
Subject: [PATCH 2/3] Update README to reference API token permission scopes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Added guidance in the API token setup section about granting
necessary permissions when creating an API client. Includes:

- List of standard development permissions needed
- Link to comprehensive PERMISSIONS.md documentation
- Added PERMISSIONS.md to "Next Steps" section for easy access

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 README.md | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/README.md b/README.md
index 93e490a..e197054 100644
--- a/README.md
+++ b/README.md
@@ -28,6 +28,15 @@ Get the Workato CLI running in 5 minutes.
 1. Log into your Workato account
 1. Navigate to **Workspace Admin** → **API clients**
 1. Click **Create API client**
+1. **Grant the necessary permissions** - For standard development, you'll need:
+   - Workspace Details (Get details)
+   - Projects & Folders (List, Create)
+   - Recipes (List, Create, Update, Start, Stop)
+   - Connections (List, Create, Update)
+   - Recipe Lifecycle Management (all permissions)
+   - Export Manifests (Create, Show, Get folder assets)
+
+   See [PERMISSIONS.md](/docs/PERMISSIONS.md) for the complete list of available scopes and recommendations.
 1. Fill out information about the client, click **Create client**
 1. Copy the generated token (starts with `wrkatrial-` for trial accounts or `wrkprod-` for production)
 
@@ -89,6 +98,7 @@ workato workspace
 - **Need detailed commands?** → See [COMMAND_REFERENCE.md](/docs/COMMAND_REFERENCE.md)
 - **Want real-world examples?** → See [USE_CASES.md](/docs/USE_CASES.md)
 - **Looking for sample recipes?** → See [examples/](/docs/examples/)
+- **Setting up API token permissions?** → See [PERMISSIONS.md](/docs/PERMISSIONS.md)
 - **Installation issues?** → See [DEVELOPER_GUIDE.md](/docs/DEVELOPER_GUIDE.md)
 - **Looking for all documentation?** → See [INDEX.md](/docs/INDEX.md)
 

From 74832177a4722675b6e4b0fb5f279d0228f6a296 Mon Sep 17 00:00:00 2001
From: Jacob Goren <jacob@scarcebytes.com>
Date: Tue, 30 Sep 2025 10:47:08 -0700
Subject: [PATCH 3/3] Remove count markers from permission section headers
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cleaned up section headers by removing count indicators (e.g., "(5/6)")
for better readability. Headers now display just the section names.

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

Co-Authored-By: Claude <noreply@anthropic.com>
---
 docs/PERMISSIONS.md | 72 ++++++++++++++++++++++-----------------------
 1 file changed, 36 insertions(+), 36 deletions(-)

diff --git a/docs/PERMISSIONS.md b/docs/PERMISSIONS.md
index 826c1ed..c46eb44 100644
--- a/docs/PERMISSIONS.md
+++ b/docs/PERMISSIONS.md
@@ -28,7 +28,7 @@ Workato API tokens use a scope-based permission system. When creating an API cli
 ### Project Assets
 Define access to core recipe building features within projects.
 
-#### Projects & Folders (7/7)
+#### Projects & Folders
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -40,7 +40,7 @@ Define access to core recipe building features within projects.
 | Delete project | `DELETE` | `/api/projects/:id` | - |
 | Update project | `PUT` | `/api/projects/:id` | - |
 
-#### Connections (5/6)
+#### Connections
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -51,7 +51,7 @@ Define access to core recipe building features within projects.
 | Disconnect Connection | `POST` | `/api/connections/:id/disconnect` | - |
 | Get picklist values | `POST` | `/api/connections/:id/pick_list` | `workato connections picklist` |
 
-#### Recipes (12/12)
+#### Recipes
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -68,7 +68,7 @@ Define access to core recipe building features within projects.
 | Reset recipe trigger | `POST` | `/api/recipes/:recipe_id/reset_trigger` | - |
 | Update connection for recipe | `PUT` | `/api/recipes/:recipe_id/connect` | `workato recipes update-connection` |
 
-#### Genies (13/13)
+#### Genies
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -86,7 +86,7 @@ Define access to core recipe building features within projects.
 | Assign user groups to genie | `POST` | `/api/agentic/genies/:id/assign_user_groups` | - |
 | Remove user groups from genie | `POST` | `/api/agentic/genies/:id/remove_user_groups` | - |
 
-#### Knowledge Bases (7/7)
+#### Knowledge Bases
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -98,7 +98,7 @@ Define access to core recipe building features within projects.
 | Get knowledge base data sources | `GET` | `/api/agentic/knowledge_bases/:id/data_sources` | - |
 | Get knowledge base recipes | `GET` | `/api/agentic/knowledge_bases/:id/recipes` | - |
 
-#### Skills (3/3)
+#### Skills
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -106,7 +106,7 @@ Define access to core recipe building features within projects.
 | Get skill | `GET` | `/api/agentic/skills/:id` | - |
 | Create skill | `POST` | `/api/agentic/skills` | - |
 
-#### Recipe Versions (3/3)
+#### Recipe Versions
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -114,7 +114,7 @@ Define access to core recipe building features within projects.
 | Get details | `GET` | `/api/recipes/:recipe_id/versions/:id` | - |
 | Update | `PUT` | `/api/recipes/:recipe_id/versions/:id` | - |
 
-#### Jobs (3/3)
+#### Jobs
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -122,13 +122,13 @@ Define access to core recipe building features within projects.
 | Get job | `GET` | `/api/recipes/:recipe_id/jobs/:job_id` | - |
 | Resume suspended job | `POST` | `/api/job/resume` | - |
 
-#### Tag Assignments (1/1)
+#### Tag Assignments
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
 | Manage tag assignments | `POST` | `/api/tags_assignments` | - |
 
-#### Test Cases (3/3)
+#### Test Cases
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -141,7 +141,7 @@ Define access to core recipe building features within projects.
 ### Recipe Lifecycle Management
 Define access to assets transfer across workspaces.
 
-#### Recipe Lifecycle Management (4/4)
+#### Recipe Lifecycle Management
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -150,7 +150,7 @@ Define access to assets transfer across workspaces.
 | Export package | `POST` | `/api/packages/export/:id` | `workato pull` |
 | Import package | `POST` | `/api/packages/import/:id` | `workato push` |
 
-#### Export Manifests (5/5)
+#### Export Manifests
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -165,7 +165,7 @@ Define access to assets transfer across workspaces.
 ### Workspace Data
 Define access to data configured at the workspace-level.
 
-#### Lookup Tables (9/9)
+#### Lookup Tables
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -179,7 +179,7 @@ Define access to data configured at the workspace-level.
 | Delete row | `DELETE` | `/api/lookup_tables/:lookup_table_id/rows/:row_id` | - |
 | Batch delete tables | `POST` | `/api/lookup_tables/batch_delete` | - |
 
-#### Data Tables (6/6)
+#### Data Tables
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -190,7 +190,7 @@ Define access to data configured at the workspace-level.
 | Update a data table | `PUT` | `/api/data_tables/:data_table_id` | - |
 | Truncate a data table | `POST` | `/api/data_tables/:data_table_id/truncate` | `workato data-tables truncate` |
 
-#### Data Table Records (4/4)
+#### Data Table Records
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -199,14 +199,14 @@ Define access to data configured at the workspace-level.
 | Delete record | `DELETE` | `/api/v1/tables/:data_table_id/records/:record_id` | - |
 | Query records | `POST` | `/api/v1/tables/:data_table_id/records/query` | - |
 
-#### Event Streams (2/2)
+#### Event Streams
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
 | Publish message to event topic | `POST` | `/api/v1/topics/:topic_id/publish` | - |
 | Read messages from event topic | `POST` | `/api/v1/topics/:topic_id/consume` | - |
 
-#### Event Streams Topics (6/6)
+#### Event Streams Topics
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -217,7 +217,7 @@ Define access to data configured at the workspace-level.
 | Update a topic | `PUT` | `/api/event_streams/topics/:topic_id` | - |
 | Purge a topic | `PUT` | `/api/event_streams/topics/:topic_id/purge` | - |
 
-#### Environment Properties (2/2)
+#### Environment Properties
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -229,7 +229,7 @@ Define access to data configured at the workspace-level.
 ### API Platform
 Define access to manage and monitor API recipe endpoints and collections.
 
-#### Certificate Bundles (5/5)
+#### Certificate Bundles
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -239,13 +239,13 @@ Define access to manage and monitor API recipe endpoints and collections.
 | Delete certificate bundle | `DELETE` | `/api/cert_bundles/:cert_bundle_id` | - |
 | Download certificate bundle | `GET` | `/api/cert_bundles/:cert_bundle_id` | - |
 
-#### API Portal (1/1)
+#### API Portal
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
 | List API Portals | `GET` | `/api/v2/api_portals` | - |
 
-#### Collections & Endpoints (5/5)
+#### Collections & Endpoints
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -255,7 +255,7 @@ Define access to manage and monitor API recipe endpoints and collections.
 | Enable endpoint | `PUT` | `/api/api_endpoints/:api_endpoint_id/enable` | - |
 | Disable endpoint | `PUT` | `/api/api_endpoints/:api_endpoint_id/disable` | - |
 
-#### Clients & Access Profiles (12/12)
+#### Clients & Access Profiles
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -277,7 +277,7 @@ Define access to manage and monitor API recipe endpoints and collections.
 ### Connector SDKs
 Define access to managing custom connectors and their versions.
 
-#### Connector SDKs (7/7)
+#### Connector SDKs
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -289,7 +289,7 @@ Define access to managing custom connectors and their versions.
 | Search custom connectors | `GET` | `/api/custom_connectors/search` | - |
 | Get custom connector code | `GET` | `/api/custom_connectors/:id/code` | `workato connectors get-code` |
 
-#### SDK CLI (2/2)
+#### SDK CLI
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -301,7 +301,7 @@ Define access to managing custom connectors and their versions.
 ### Custom OAuth Profiles
 Define access to manage custom OAuth profiles.
 
-#### Custom OAuth Profiles (5/5)
+#### Custom OAuth Profiles
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -316,7 +316,7 @@ Define access to manage custom OAuth profiles.
 ### On-Prem Groups and Agents
 Define access to manage connectivity to authorized on-prem applications through groups and agents.
 
-#### On-Prem Groups (7/7)
+#### On-Prem Groups
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -328,7 +328,7 @@ Define access to manage connectivity to authorized on-prem applications through
 | Delete | `DELETE` | `/api/on_prem_groups/:id` | - |
 | Get agents in group | `GET` | `/api/on_prem_groups/:id/agents` | - |
 
-#### On-Prem Agents (8/8)
+#### On-Prem Agents
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -346,7 +346,7 @@ Define access to manage connectivity to authorized on-prem applications through
 ### Partner Marketplace
 Define access to endpoints that help in the creation of a connector marketplace for your customers.
 
-#### Connectors (2/2)
+#### Connectors
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -358,7 +358,7 @@ Define access to endpoints that help in the creation of a connector marketplace
 ### Workspace Collaborators
 Define access to manage collaborators and their roles in your workspace.
 
-#### Collaborators (6/6)
+#### Collaborators
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -369,7 +369,7 @@ Define access to manage collaborators and their roles in your workspace.
 | Get collaborator privileges | `GET` | `/api/members/:id/privileges` | - |
 | Delete collaborator | `DELETE` | `/api/members/:id` | - |
 
-#### Collaborator Roles (3/3)
+#### Collaborator Roles
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -382,7 +382,7 @@ Define access to manage collaborators and their roles in your workspace.
 ### Workspace Details
 Define access to retrieval of workspace details.
 
-#### Workspace Details (1/1)
+#### Workspace Details
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -393,19 +393,19 @@ Define access to retrieval of workspace details.
 ### Environment Management
 Define access to environment management operations.
 
-#### Secrets Management (1/1)
+#### Secrets Management
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
 | Clear secrets cache | `POST` | `/api/secrets_management/clear_cache` | - |
 
-#### Audit Log (1/1)
+#### Audit Log
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
 | Get audit log | `GET` | `/api/activity_logs` | - |
 
-#### Tags (4/4)
+#### Tags
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -419,7 +419,7 @@ Define access to environment management operations.
 ### Developer API Clients
 Define access to manage API clients.
 
-#### API Clients (6/6)
+#### API Clients
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|
@@ -430,7 +430,7 @@ Define access to manage API clients.
 | Delete API client | `DELETE` | `/api/developer_api_clients/:id` | - |
 | Regenerate API client token | `POST` | `/api/developer_api_clients/:id/regenerate` | - |
 
-#### API Client Roles (2/2)
+#### API Client Roles
 
 | Permission | HTTP Method | Endpoint | CLI Commands |
 |------------|-------------|----------|--------------|