@aifabrix/builder 2.38.0 → 2.39.1

package/.cursor/rules/project-rules.mdc

@@ -262,6 +262,8 @@ const appResponse = await registerApplication(controllerUrl, environment, data,
 - Gradually migrate modules to use centralized API client
 - Eventually deprecate direct usage of `lib/utils/api.js`
 
+**API Permissions**: When adding or changing `lib/api` functions that call Controller or Dataplane, document required permissions. See [permissions-guide.md](permissions-guide.md) for how to update `@requiresPermission` JSDoc and [docs/commands/permissions.md](../docs/commands/permissions.md).
+
 ## Code Style
 
 ### JavaScript Conventions
@@ -880,6 +882,7 @@ Define request/response types using JSDoc `@typedef`:
 - ✅ Use centralized API client (`lib/api/`) for new API calls
 - ✅ Define request/response types using JSDoc `@typedef` in `lib/api/types/`
 - ✅ Use domain-specific API modules (`lib/api/*.api.js`) instead of direct `makeApiCall`
+- ✅ When adding lib/api functions that call Controller/Dataplane, add `@requiresPermission` JSDoc per [permissions-guide.md](permissions-guide.md)
 
 ### Must Not Do (❌)
 - ❌ Never hardcode secrets, passwords, or tokens

package/integration/hubspot/hubspot-deploy.json

@@ -22,9 +22,6 @@
     "description": "HubSpot CRM integration with OpenAPI support for companies, contacts, and deals",
     "type": "openapi",
     "enabled": true,
-    "environment": {
-      "baseUrl": "https://api.hubapi.com"
-    },
     "authentication": {
       "type": "oauth2",
       "mode": "oauth2",

package/integration/hubspot/hubspot-system.json

@@ -4,9 +4,6 @@
   "description": "HubSpot CRM integration with OpenAPI support for companies, contacts, and deals",
   "type": "openapi",
   "enabled": true,
-  "environment": {
-    "baseUrl": "https://api.hubapi.com"
-  },
   "authentication": {
     "type": "oauth2",
     "mode": "oauth2",

package/lib/api/applications.api.js

@@ -9,6 +9,7 @@ const { ApiClient } = require('./index');
 /**
  * List all template applications
  * GET /api/v1/applications
+ * @requiresPermission {Controller} applications:read
  * @async
  * @function listApplications
  * @param {string} controllerUrl - Controller base URL
@@ -32,6 +33,7 @@ async function listApplications(controllerUrl, authConfig, options = {}) {
 /**
  * Create new template application
  * POST /api/v1/applications
+ * @requiresPermission {Controller} applications:create
  * @async
  * @function createApplication
  * @param {string} controllerUrl - Controller base URL
@@ -55,6 +57,7 @@ async function createApplication(controllerUrl, authConfig, applicationData) {
 /**
  * Get template application details
  * GET /api/v1/applications/{appKey}
+ * @requiresPermission {Controller} applications:read
  * @async
  * @function getApplication
  * @param {string} controllerUrl - Controller base URL
@@ -71,6 +74,7 @@ async function getApplication(controllerUrl, appKey, authConfig) {
 /**
  * Update template application
  * PATCH /api/v1/applications/{appKey}
+ * @requiresPermission {Controller} applications:update
  * @async
  * @function updateApplication
  * @param {string} controllerUrl - Controller base URL
@@ -95,6 +99,7 @@ async function updateApplication(controllerUrl, appKey, authConfig, updateData)
 /**
  * Delete template application
  * DELETE /api/v1/applications/{appKey}
+ * @requiresPermission {Controller} applications:delete
  * @async
  * @function deleteApplication
  * @param {string} controllerUrl - Controller base URL
@@ -111,6 +116,7 @@ async function deleteApplication(controllerUrl, appKey, authConfig) {
 /**
  * Register application in an environment
  * POST /api/v1/environments/{envKey}/applications/register
+ * @requiresPermission {Controller} environments-applications:create
  * @async
  * @function registerApplication
  * @param {string} controllerUrl - Controller base URL
@@ -139,6 +145,7 @@ async function registerApplication(controllerUrl, envKey, authConfig, registrati
 /**
  * Rotate application secret
  * POST /api/v1/environments/{envKey}/applications/{appKey}/rotate-secret
+ * @requiresPermission {Controller} environments-applications:update
  * @async
  * @function rotateApplicationSecret
  * @param {string} controllerUrl - Controller base URL
@@ -156,8 +163,7 @@ async function rotateApplicationSecret(controllerUrl, envKey, appKey, authConfig
 /**
  * Get application status (metadata only, no configuration)
  * GET /api/v1/environments/{envKey}/applications/{appKey}/status
- * Auth: bearer token or pipeline client credentials for that application.
- *
+ * @requiresPermission {Controller} Bearer or app client credentials (environments-applications:read)
  * @async
  * @function getApplicationStatus
  * @param {string} controllerUrl - Controller base URL

package/lib/api/auth.api.js

@@ -9,6 +9,7 @@ const { ApiClient } = require('./index');
 /**
  * Get authentication token using client credentials
  * POST /api/v1/auth/token
+ * @requiresPermission {Controller} Client credentials (no scope in spec)
  * @async
  * @function getToken
  * @param {string} clientId - Client ID
@@ -30,6 +31,7 @@ async function getToken(clientId, clientSecret, controllerUrl) {
 /**
  * Get client token for frontend application
  * GET/POST /api/v1/auth/client-token
+ * @requiresPermission {Controller} Client credentials or unauthenticated
  * @async
  * @function getClientToken
  * @param {string} controllerUrl - Controller base URL
@@ -50,6 +52,7 @@ async function getClientToken(controllerUrl, method = 'POST') {
 /**
  * Get current user information
  * GET /api/v1/auth/user
+ * @requiresPermission {Controller} auth:read
  * @async
  * @function getAuthUser
  * @param {string} controllerUrl - Controller base URL
@@ -65,6 +68,7 @@ async function getAuthUser(controllerUrl, authConfig) {
 /**
  * Get login URL for OAuth2 authorization flow
  * GET /api/v1/auth/login
+ * @requiresPermission {Controller} Client credentials
  * @async
  * @function getAuthLogin
  * @param {string} controllerUrl - Controller base URL
@@ -84,6 +88,7 @@ async function getAuthLogin(controllerUrl, redirect, state, authConfig) {
 /**
  * Initiate OAuth2 Device Code Flow
  * POST /api/v1/auth/login
+ * @requiresPermission {Controller} Public (no auth required for device code initiation)
  * @async
  * @function initiateDeviceCodeFlow
  * @param {string} controllerUrl - Controller base URL
@@ -122,6 +127,7 @@ async function initiateDeviceCodeFlow(controllerUrl, environment, scope) {
 /**
  * Poll for device code token
  * POST /api/v1/auth/login/device/token
+ * @requiresPermission {Controller} Public
  * @async
  * @function pollDeviceCodeToken
  * @param {string} deviceCode - Device code from initiate device code flow
@@ -139,6 +145,7 @@ async function pollDeviceCodeToken(deviceCode, controllerUrl) {
 /**
  * Refresh device code access token
  * POST /api/v1/auth/login/device/refresh
+ * @requiresPermission {Controller} Bearer token (refresh token)
  * @async
  * @function refreshDeviceToken
  * @param {string} refreshToken - Refresh token obtained from device code token flow
@@ -156,6 +163,7 @@ async function refreshDeviceToken(refreshToken, controllerUrl) {
 /**
  * Refresh user access token
  * POST /api/v1/auth/refresh
+ * @requiresPermission {Controller} Bearer token (refresh token)
  * @async
  * @function refreshUserToken
  * @param {string} refreshToken - Refresh token obtained from OAuth callback flow
@@ -173,6 +181,7 @@ async function refreshUserToken(refreshToken, controllerUrl) {
 /**
  * Validate authentication token
  * POST /api/v1/auth/validate
+ * @requiresPermission {Controller} auth:read or client credentials
  * @async
  * @function validateToken
  * @param {string} token - JWT token to validate
@@ -202,6 +211,7 @@ async function validateToken(token, controllerUrl, authConfig, environment, appl
 /**
  * Get user roles
  * GET /api/v1/auth/roles
+ * @requiresPermission {Controller} auth:read
  * @async
  * @function getAuthRoles
  * @param {string} controllerUrl - Controller base URL
@@ -221,6 +231,7 @@ async function getAuthRoles(controllerUrl, authConfig, environment, application)
 /**
  * Refresh user roles
  * GET /api/v1/auth/roles/refresh
+ * @requiresPermission {Controller} auth:read
  * @async
  * @function refreshAuthRoles
  * @param {string} controllerUrl - Controller base URL
@@ -236,6 +247,7 @@ async function refreshAuthRoles(controllerUrl, authConfig) {
 /**
  * Get user permissions
  * GET /api/v1/auth/permissions
+ * @requiresPermission {Controller} auth:read
  * @async
  * @function getAuthPermissions
  * @param {string} controllerUrl - Controller base URL
@@ -255,6 +267,7 @@ async function getAuthPermissions(controllerUrl, authConfig, environment, applic
 /**
  * Refresh user permissions
  * GET /api/v1/auth/permissions/refresh
+ * @requiresPermission {Controller} auth:read
  * @async
  * @function refreshAuthPermissions
  * @param {string} controllerUrl - Controller base URL
@@ -270,6 +283,7 @@ async function refreshAuthPermissions(controllerUrl, authConfig) {
 /**
  * Get device code login diagnostics
  * GET /api/v1/auth/login/diagnostics
+ * @requiresPermission {Controller} Public
  * @async
  * @function getAuthLoginDiagnostics
  * @param {string} controllerUrl - Controller base URL

package/lib/api/credentials.api.js

@@ -10,7 +10,7 @@ const { ApiClient } = require('./index');
  * List credentials from controller or dataplane
  * GET /api/v1/credential
  * Used by `aifabrix credential list`. Call with controller or dataplane base URL per deployment.
- *
+ * @requiresPermission {Dataplane} credential:read (when baseUrl is dataplane; controller may differ)
  * @async
  * @function listCredentials
  * @param {string} baseUrl - Controller or dataplane base URL

package/lib/api/datasources-core.api.js

@@ -1,67 +1,82 @@
 /**
- * @fileoverview Datasources Core API functions
+ * @fileoverview Datasources Core API functions (Dataplane /api/v1/external/). All functions require Dataplane auth; scope per endpoint in dataplane OpenAPI (e.g. external-system:read, external-system:create).
  * @author AI Fabrix Team
  * @version 2.0.0
  */
 
 const { ApiClient } = require('./index');
 
+/** @requiresPermission {Dataplane} external-system:read (datasource list) */
 async function listDatasources(dataplaneUrl, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get('/api/v1/external/', { params: options });
 }
+/** @requiresPermission {Dataplane} external-system:create */
 async function createDatasource(dataplaneUrl, authConfig, datasourceData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post('/api/v1/external/', { body: datasourceData });
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function getDatasource(dataplaneUrl, sourceIdOrKey, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}`);
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function updateDatasource(dataplaneUrl, sourceIdOrKey, authConfig, updateData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.put(`/api/v1/external/${sourceIdOrKey}`, { body: updateData });
 }
+/** @requiresPermission {Dataplane} external-system:delete */
 async function deleteDatasource(dataplaneUrl, sourceIdOrKey, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.delete(`/api/v1/external/${sourceIdOrKey}`);
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function getDatasourceConfig(dataplaneUrl, sourceIdOrKey, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/config`);
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function publishDatasource(dataplaneUrl, sourceIdOrKey, authConfig, publishData = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/publish`, { body: publishData });
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function rollbackDatasource(dataplaneUrl, sourceIdOrKey, authConfig, rollbackData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/rollback`, { body: rollbackData });
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function testDatasource(dataplaneUrl, sourceIdOrKey, authConfig, testData = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/test`, { body: testData });
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function listDatasourceOpenAPIEndpoints(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/openapi-endpoints`, { params: options });
 }
+/** @requiresPermission {Dataplane} audit:read or external-system:read */
 async function listExecutionLogs(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/executions`, { params: options });
 }
+/** @requiresPermission {Dataplane} audit:read or external-system:read */
 async function getExecutionLog(dataplaneUrl, sourceIdOrKey, executionId, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/executions/${executionId}`);
 }
+/** @requiresPermission {Dataplane} audit:read */
 async function listAllExecutionLogs(dataplaneUrl, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get('/api/v1/external/executions', { params: options });
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function bulkOperation(dataplaneUrl, sourceIdOrKey, authConfig, bulkData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/bulk`, { body: bulkData });
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function getDatasourceStatus(dataplaneUrl, sourceIdOrKey, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/status`);

package/lib/api/datasources-extended.api.js

@@ -1,43 +1,52 @@
 /**
- * @fileoverview Datasources Extended API functions (records, grants, policies, sync, documents)
+ * @fileoverview Datasources Extended API functions (records, grants, policies, sync, documents). All require Dataplane; scope per endpoint in dataplane OpenAPI.
  * @author AI Fabrix Team
  * @version 2.0.0
  */
 
 const { ApiClient } = require('./index');
 
+/** @requiresPermission {Dataplane} external-system:read (records) */
 async function listRecords(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/records`, { params: options });
 }
+/** @requiresPermission {Dataplane} external-system:create */
 async function createRecord(dataplaneUrl, sourceIdOrKey, authConfig, recordData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/records`, { body: recordData });
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function getRecord(dataplaneUrl, sourceIdOrKey, recordIdOrKey, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/records/${recordIdOrKey}`);
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function updateRecord(dataplaneUrl, sourceIdOrKey, recordIdOrKey, authConfig, updateData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.put(`/api/v1/external/${sourceIdOrKey}/records/${recordIdOrKey}`, { body: updateData });
 }
+/** @requiresPermission {Dataplane} external-system:delete */
 async function deleteRecord(dataplaneUrl, sourceIdOrKey, recordIdOrKey, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.delete(`/api/v1/external/${sourceIdOrKey}/records/${recordIdOrKey}`);
 }
+/** @requiresPermission {Dataplane} external-system:read (grants) */
 async function listGrants(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/grants`, { params: options });
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function createGrant(dataplaneUrl, sourceIdOrKey, authConfig, grantData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/grants`, { body: grantData });
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function getGrant(dataplaneUrl, sourceIdOrKey, grantIdOrKey, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/grants/${grantIdOrKey}`);
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function updateGrant(dataplaneUrl, sourceIdOrKey, grantIdOrKey, authConfig, updateData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.put(`/api/v1/external/${sourceIdOrKey}/grants/${grantIdOrKey}`, { body: updateData });
@@ -46,10 +55,12 @@ async function deleteGrant(dataplaneUrl, sourceIdOrKey, grantIdOrKey, authConfig
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.delete(`/api/v1/external/${sourceIdOrKey}/grants/${grantIdOrKey}`);
 }
+/** @requiresPermission {Dataplane} external-system:read (policies) */
 async function listPolicies(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/policies`, { params: options });
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function attachPolicy(dataplaneUrl, sourceIdOrKey, authConfig, policyData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/policies`, { body: policyData });
@@ -58,6 +69,7 @@ async function detachPolicy(dataplaneUrl, sourceIdOrKey, policyIdOrKey, authConf
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.delete(`/api/v1/external/${sourceIdOrKey}/policies/${policyIdOrKey}`);
 }
+/** @requiresPermission {Dataplane} external-system:read (sync) */
 async function listSyncJobs(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/sync`, { params: options });
@@ -66,10 +78,12 @@ async function createSyncJob(dataplaneUrl, sourceIdOrKey, authConfig, syncData)
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/sync`, { body: syncData });
 }
+/** @requiresPermission {Dataplane} external-system:read */
 async function getSyncJob(dataplaneUrl, sourceIdOrKey, syncJobId, authConfig) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/${sourceIdOrKey}/sync/${syncJobId}`);
 }
+/** @requiresPermission {Dataplane} external-system:update */
 async function updateSyncJob(dataplaneUrl, sourceIdOrKey, syncJobId, authConfig, updateData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.put(`/api/v1/external/${sourceIdOrKey}/sync/${syncJobId}`, { body: updateData });
@@ -78,14 +92,17 @@ async function executeSyncJob(dataplaneUrl, sourceIdOrKey, syncJobId, authConfig
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/${sourceIdOrKey}/sync/${syncJobId}/execute`);
 }
+/** @requiresPermission {Dataplane} document-record or external-system scope */
 async function validateDocuments(dataplaneUrl, sourceIdOrKey, authConfig, validateData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/data-sources/${sourceIdOrKey}/documents/validate`, { body: validateData });
 }
+/** @requiresPermission {Dataplane} document-record or external-system scope */
 async function bulkDocuments(dataplaneUrl, sourceIdOrKey, authConfig, bulkData) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.post(`/api/v1/external/data-sources/${sourceIdOrKey}/documents/bulk`, { body: bulkData });
 }
+/** @requiresPermission {Dataplane} document-record:read or external-system:read */
 async function listDocuments(dataplaneUrl, sourceIdOrKey, authConfig, options = {}) {
   const client = new ApiClient(dataplaneUrl, authConfig);
   return await client.get(`/api/v1/external/data-sources/${sourceIdOrKey}/documents`, { params: options });

package/lib/api/deployments.api.js

@@ -9,6 +9,7 @@ const { ApiClient } = require('./index');
 /**
  * Deploy an application to an environment
  * POST /api/v1/environments/{envKey}/applications/deploy
+ * @requiresPermission {Controller} applications:deploy
  * @async
  * @function deployApplication
  * @param {string} controllerUrl - Controller base URL
@@ -32,6 +33,7 @@ async function deployApplication(controllerUrl, envKey, authConfig, deployData)
 /**
  * Deploy environment infrastructure
  * POST /api/v1/environments/{envKey}/deploy
+ * @requiresPermission {Controller} controller:deploy
  * @async
  * @function deployEnvironment
  * @param {string} controllerUrl - Controller base URL
@@ -53,6 +55,7 @@ async function deployEnvironment(controllerUrl, envKey, authConfig, deployData)
 /**
  * List deployments for an environment
  * GET /api/v1/environments/{envKey}/deployments
+ * @requiresPermission {Controller} deployments:read
  * @async
  * @function listDeployments
  * @param {string} controllerUrl - Controller base URL
@@ -79,6 +82,7 @@ async function listDeployments(controllerUrl, envKey, authConfig, options = {})
 /**
  * Get deployment with jobs and logs
  * GET /api/v1/environments/{envKey}/deployments/{deploymentId}
+ * @requiresPermission {Controller} deployments:read
  * @async
  * @function getDeployment
  * @param {string} controllerUrl - Controller base URL
@@ -96,6 +100,7 @@ async function getDeployment(controllerUrl, envKey, deploymentId, authConfig) {
 /**
  * Get deployment job logs
  * GET /api/v1/environments/{envKey}/deployments/{deploymentId}/logs
+ * @requiresPermission {Controller} deployments:read
  * @async
  * @function getDeploymentLogs
  * @param {string} controllerUrl - Controller base URL
@@ -119,7 +124,7 @@ async function getDeploymentLogs(controllerUrl, envKey, deploymentId, authConfig
 /**
  * List deployments for a single application in an environment
  * GET /api/v1/environments/{envKey}/applications/{appKey}/deployments
- *
+ * @requiresPermission {Controller} deployments:read
  * @async
  * @function listApplicationDeployments
  * @param {string} controllerUrl - Controller base URL

package/lib/api/environments.api.js

@@ -9,6 +9,7 @@ const { ApiClient } = require('./index');
 /**
  * List all environments
  * GET /api/v1/environments
+ * @requiresPermission {Controller} environments:read
  * @async
  * @function listEnvironments
  * @param {string} controllerUrl - Controller base URL
@@ -34,6 +35,7 @@ async function listEnvironments(controllerUrl, authConfig, options = {}) {
 /**
  * Create new environment
  * POST /api/v1/environments
+ * @requiresPermission {Controller} environments:create
  * @async
  * @function createEnvironment
  * @param {string} controllerUrl - Controller base URL
@@ -55,6 +57,7 @@ async function createEnvironment(controllerUrl, authConfig, environmentData) {
 /**
  * Get environment by key
  * GET /api/v1/environments/{envKey}
+ * @requiresPermission {Controller} environments:read
  * @async
  * @function getEnvironment
  * @param {string} controllerUrl - Controller base URL
@@ -71,6 +74,7 @@ async function getEnvironment(controllerUrl, envKey, authConfig) {
 /**
  * Update environment by key
  * PATCH /api/v1/environments/{envKey}
+ * @requiresPermission {Controller} environments:update
  * @async
  * @function updateEnvironment
  * @param {string} controllerUrl - Controller base URL
@@ -91,6 +95,7 @@ async function updateEnvironment(controllerUrl, envKey, authConfig, updateData)
 /**
  * Get environment status
  * GET /api/v1/environments/{envKey}/status
+ * @requiresPermission {Controller} environments:read
  * @async
  * @function getEnvironmentStatus
  * @param {string} controllerUrl - Controller base URL
@@ -107,6 +112,7 @@ async function getEnvironmentStatus(controllerUrl, envKey, authConfig) {
 /**
  * List applications in an environment
  * GET /api/v1/environments/{envKey}/applications
+ * @requiresPermission {Controller} environments-applications:read
  * @async
  * @function listEnvironmentApplications
  * @param {string} controllerUrl - Controller base URL
@@ -131,6 +137,7 @@ async function listEnvironmentApplications(controllerUrl, envKey, authConfig, op
 /**
  * List deployments for environment
  * GET /api/v1/environments/{envKey}/deployments
+ * @requiresPermission {Controller} deployments:read
  * @async
  * @function listEnvironmentDeployments
  * @param {string} controllerUrl - Controller base URL
@@ -156,6 +163,7 @@ async function listEnvironmentDeployments(controllerUrl, envKey, authConfig, opt
 /**
  * List roles for environment
  * GET /api/v1/environments/{envKey}/roles
+ * @requiresPermission {Controller} environments:read
  * @async
  * @function listEnvironmentRoles
  * @param {string} controllerUrl - Controller base URL
@@ -172,6 +180,7 @@ async function listEnvironmentRoles(controllerUrl, envKey, authConfig) {
 /**
  * Map role to groups for environment
  * PATCH /api/v1/environments/{envKey}/roles/{value}/groups
+ * @requiresPermission {Controller} environments:update
  * @async
  * @function updateRoleGroups
  * @param {string} controllerUrl - Controller base URL
@@ -192,6 +201,7 @@ async function updateRoleGroups(controllerUrl, envKey, roleValue, authConfig, gr
 /**
  * Get application details in an environment
  * GET /api/v1/environments/{envKey}/applications/{appKey}
+ * @requiresPermission {Controller} environments-applications:read
  * @async
  * @function getEnvironmentApplication
  * @param {string} controllerUrl - Controller base URL
@@ -209,6 +219,7 @@ async function getEnvironmentApplication(controllerUrl, envKey, appKey, authConf
 /**
  * List datasources in an environment
  * GET /api/v1/environments/{envKey}/datasources
+ * @requiresPermission {Controller} environments:read (or datasources scope per controller spec)
  * @async
  * @function listEnvironmentDatasources
  * @param {string} controllerUrl - Controller base URL

package/lib/api/external-systems.api.js

@@ -9,6 +9,7 @@ const { ApiClient } = require('./index');
 /**
  * List external systems
  * GET /api/v1/external/systems
+ * @requiresPermission {Dataplane} external-system:read
  * @async
  * @function listExternalSystems
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -32,6 +33,7 @@ async function listExternalSystems(dataplaneUrl, authConfig, options = {}) {
 /**
  * Create external system
  * POST /api/v1/external/systems
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function createExternalSystem
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -50,12 +52,16 @@ async function createExternalSystem(dataplaneUrl, authConfig, systemData) {
 /**
  * Get external system details
  * GET /api/v1/external/systems/{systemIdOrKey}
+ * @requiresPermission {Dataplane} external-system:read
  * @async
  * @function getExternalSystem
  * @param {string} dataplaneUrl - Dataplane base URL
  * @param {string} systemIdOrKey - System ID or key
  * @param {Object} authConfig - Authentication configuration
- * @returns {Promise<Object>} External system details response
+ * @returns {Promise<Object>} External system details response. May include optional fields:
+ *   - {string} [mcpServerUrl] - Full URL of external system MCP server when configured
+ *   - {string} [apiDocumentUrl] - Full URL of API document (OpenAPI spec) when configured
+ *   - {string} [openApiDocsPageUrl] - Full URL of dataplane API docs page when showOpenApiDocs is true
  * @throws {Error} If request fails
  */
 async function getExternalSystem(dataplaneUrl, systemIdOrKey, authConfig) {
@@ -66,6 +72,7 @@ async function getExternalSystem(dataplaneUrl, systemIdOrKey, authConfig) {
 /**
  * Update external system
  * PUT /api/v1/external/systems/{systemIdOrKey}
+ * @requiresPermission {Dataplane} external-system:update
  * @async
  * @function updateExternalSystem
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -85,6 +92,7 @@ async function updateExternalSystem(dataplaneUrl, systemIdOrKey, authConfig, upd
 /**
  * Delete external system (soft delete)
  * DELETE /api/v1/external/systems/{systemIdOrKey}
+ * @requiresPermission {Dataplane} external-system:delete
  * @async
  * @function deleteExternalSystem
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -101,6 +109,7 @@ async function deleteExternalSystem(dataplaneUrl, systemIdOrKey, authConfig) {
 /**
  * Get full config with application schema and dataSources
  * GET /api/v1/external/systems/{systemIdOrKey}/config
+ * @requiresPermission {Dataplane} external-system:read
  * @async
  * @function getExternalSystemConfig
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -117,6 +126,7 @@ async function getExternalSystemConfig(dataplaneUrl, systemIdOrKey, authConfig)
 /**
  * Create external system from integration template
  * POST /api/v1/external/systems/from-template
+ * @requiresPermission {Dataplane} external-system:create
  * @async
  * @function createFromTemplate
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -138,6 +148,7 @@ async function createFromTemplate(dataplaneUrl, authConfig, templateData) {
 /**
  * List OpenAPI files for system
  * GET /api/v1/external/systems/{systemIdOrKey}/openapi-files
+ * @requiresPermission {Dataplane} external-system:read
  * @async
  * @function listOpenAPIFiles
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -157,6 +168,7 @@ async function listOpenAPIFiles(dataplaneUrl, systemIdOrKey, authConfig, options
 /**
  * List OpenAPI endpoints for system
  * GET /api/v1/external/systems/{systemIdOrKey}/openapi-endpoints
+ * @requiresPermission {Dataplane} external-system:read
  * @async
  * @function listOpenAPIEndpoints
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -176,6 +188,7 @@ async function listOpenAPIEndpoints(dataplaneUrl, systemIdOrKey, authConfig, opt
 /**
  * Publish external system
  * POST /api/v1/external/systems/{systemIdOrKey}/publish
+ * @requiresPermission {Dataplane} external-system:update (or publish scope per dataplane spec)
  * @async
  * @function publishExternalSystem
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -196,6 +209,7 @@ async function publishExternalSystem(dataplaneUrl, systemIdOrKey, authConfig, pu
 /**
  * Rollback external system to version
  * POST /api/v1/external/systems/{systemIdOrKey}/rollback
+ * @requiresPermission {Dataplane} external-system:update
  * @async
  * @function rollbackExternalSystem
  * @param {string} dataplaneUrl - Dataplane base URL
@@ -216,6 +230,7 @@ async function rollbackExternalSystem(dataplaneUrl, systemIdOrKey, authConfig, r
 /**
  * Save external system as integration template
  * POST /api/v1/external/systems/{systemIdOrKey}/save-template
+ * @requiresPermission {Dataplane} external-system:update
  * @async
  * @function saveAsTemplate
  * @param {string} dataplaneUrl - Dataplane base URL