From 126e43569d4a408acbaa25f1009275b6972bd2d3 Mon Sep 17 00:00:00 2001 From: Gaston Yelmini Date: Wed, 18 Mar 2026 14:30:07 -0300 Subject: [PATCH 1/5] feat(core): add StepAuthorization interface to StepMetadata Add structured authorization requirements to step metadata, replacing the flat permissions array with a typed interface that supports permissions, roles, OAuth scopes, and required APIs. The existing permissions property is preserved but marked as deprecated. --- .../integration-sdk-core/src/types/step.ts | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) diff --git a/packages/integration-sdk-core/src/types/step.ts b/packages/integration-sdk-core/src/types/step.ts index d72532fce..1c8926958 100644 --- a/packages/integration-sdk-core/src/types/step.ts +++ b/packages/integration-sdk-core/src/types/step.ts @@ -215,6 +215,35 @@ export interface StepGraphObjectMetadataProperties { mappedRelationships?: StepMappedRelationshipMetadata[]; } +/** + * Describes the external authorization requirements that must be satisfied + * for an integration step to execute successfully. + * + * Each property represents a specific type of authorization requirement. + * Integrations declare only the properties that apply to their provider. + */ +export interface StepAuthorization { + /** + * IAM permissions granted to the integration principal. + */ + permissions?: string[]; + + /** + * RBAC role assignments bound to the integration principal. + */ + roles?: string[]; + + /** + * OAuth scopes granted to the application or service principal. + */ + oauthScopes?: string[]; + + /** + * APIs or services that must be enabled in the target environment. + */ + apis?: string[]; +} + export type StepMetadata = StepGraphObjectMetadataProperties & { /* * Identifier used to reference and track steps @@ -259,6 +288,25 @@ export type StepMetadata = StepGraphObjectMetadataProperties & { * */ ingestionSourceId?: string; + + /** + * An optional array of provider API permissions required + * for this step to execute successfully. Used to document + * and communicate required API token scopes to users. + * + * @deprecated Use `authorization` instead for structured permission declarations. + */ + permissions?: string[]; + + /** + * Describes the external authorization requirements that must be satisfied + * for this step to execute successfully. Each property represents a + * specific type of authorization requirement and is optional, allowing + * integrations to declare only what applies to their provider. + * + * Used to generate documentation and communicate setup requirements to users. + */ + authorization?: StepAuthorization; }; export type StepExecutionHandlerWrapperFunction< From d0234b709885756c618af9b89c41a32895770140 Mon Sep 17 00:00:00 2001 From: Gaston Yelmini Date: Wed, 18 Mar 2026 14:32:17 -0300 Subject: [PATCH 2/5] fix(core): remove deprecated annotation from permissions field --- packages/integration-sdk-core/src/types/step.ts | 2 -- 1 file changed, 2 deletions(-) diff --git a/packages/integration-sdk-core/src/types/step.ts b/packages/integration-sdk-core/src/types/step.ts index 1c8926958..79da9b6f7 100644 --- a/packages/integration-sdk-core/src/types/step.ts +++ b/packages/integration-sdk-core/src/types/step.ts @@ -293,8 +293,6 @@ export type StepMetadata = StepGraphObjectMetadataProperties & { * An optional array of provider API permissions required * for this step to execute successfully. Used to document * and communicate required API token scopes to users. - * - * @deprecated Use `authorization` instead for structured permission declarations. */ permissions?: string[]; From caf73e248cb6008a4b0a71c070f7c2896c01ca5c Mon Sep 17 00:00:00 2001 From: Gaston Yelmini Date: Wed, 18 Mar 2026 14:33:43 -0300 Subject: [PATCH 3/5] feat(core): add endpoints and licenses to StepAuthorization --- packages/integration-sdk-core/src/types/step.ts | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/packages/integration-sdk-core/src/types/step.ts b/packages/integration-sdk-core/src/types/step.ts index 79da9b6f7..70b7eb339 100644 --- a/packages/integration-sdk-core/src/types/step.ts +++ b/packages/integration-sdk-core/src/types/step.ts @@ -242,6 +242,16 @@ export interface StepAuthorization { * APIs or services that must be enabled in the target environment. */ apis?: string[]; + + /** + * API endpoints that this step makes requests to. + */ + endpoints?: string[]; + + /** + * Product licenses or SKUs required in the target environment. + */ + licenses?: string[]; } export type StepMetadata = StepGraphObjectMetadataProperties & { From f54d2ad595aa1c1065f3243dc1433e6c603ea1e0 Mon Sep 17 00:00:00 2001 From: Gaston Yelmini Date: Wed, 18 Mar 2026 14:34:38 -0300 Subject: [PATCH 4/5] feat(core): add documentationLinks to StepAuthorization --- packages/integration-sdk-core/src/types/step.ts | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/packages/integration-sdk-core/src/types/step.ts b/packages/integration-sdk-core/src/types/step.ts index 70b7eb339..20a080bb6 100644 --- a/packages/integration-sdk-core/src/types/step.ts +++ b/packages/integration-sdk-core/src/types/step.ts @@ -252,6 +252,11 @@ export interface StepAuthorization { * Product licenses or SKUs required in the target environment. */ licenses?: string[]; + + /** + * Links to provider documentation relevant to this step's setup or configuration. + */ + documentationLinks?: string[]; } export type StepMetadata = StepGraphObjectMetadataProperties & { From 99856bbda9d093acb6af5b575065bfe152b333a2 Mon Sep 17 00:00:00 2001 From: Gaston Yelmini Date: Wed, 18 Mar 2026 14:36:34 -0300 Subject: [PATCH 5/5] fix(core): remove unused permissions field from StepMetadata --- packages/integration-sdk-core/src/types/step.ts | 7 ------- 1 file changed, 7 deletions(-) diff --git a/packages/integration-sdk-core/src/types/step.ts b/packages/integration-sdk-core/src/types/step.ts index 20a080bb6..8597970ab 100644 --- a/packages/integration-sdk-core/src/types/step.ts +++ b/packages/integration-sdk-core/src/types/step.ts @@ -304,13 +304,6 @@ export type StepMetadata = StepGraphObjectMetadataProperties & { */ ingestionSourceId?: string; - /** - * An optional array of provider API permissions required - * for this step to execute successfully. Used to document - * and communicate required API token scopes to users. - */ - permissions?: string[]; - /** * Describes the external authorization requirements that must be satisfied * for this step to execute successfully. Each property represents a