@celigo/api-specs 0.2.38 → 0.2.40

package/dist/iclient.yml

@@ -25,7 +25,8 @@ tags:
 
       Each iClient targets one `provider` — the provider determines
       which credential sub-object (`oauth2`, `netsuite`, `salesforce`,
-      `ebay`, `amazonmws`, `azureserviceprincipal`) is required.
+      `ebay`, `amazonmws`, `azureserviceprincipal`, `googleserviceaccount`,
+      `awsIam`) is required.
       Secrets are stored encrypted and returned masked as `"******"`.
 
       ## iClient schema
@@ -163,6 +164,14 @@ paths:
                     clientId: a1b2c3d4-e5f6-7890-abcd-ef1234567890
                     clientSecret: my-client-secret
                     tenantId: f0e1d2c3-b4a5-6789-0abc-def012345678
+              awsIam:
+                summary: AWS IAM role for HTTP awsiam connections
+                value:
+                  name: AWS IAM - orders account
+                  provider: awsIam
+                  awsIam:
+                    externalId: celigo-7f3a9c2e1b
+                    roleArn: arn:aws:iam::123456789012:role/celigo-http-adaptor-orders
       responses:
         '201':
           description: iClient created.
@@ -192,6 +201,20 @@ paths:
                         - example.com
                       grantType: clientcredentials
                       useNewAuthFailSchema: true
+                awsIam:
+                  summary: Created AWS IAM iClient (role fields returned in clear)
+                  value:
+                    _id: 6ab1f51c7b3d01a908423f0a
+                    name: AWS IAM - orders account
+                    published: false
+                    lastModified: '2026-09-21T20:25:16.371Z'
+                    provider: awsIam
+                    enableJWT: false
+                    enableIClientReferences: false
+                    formType: http
+                    awsIam:
+                      externalId: celigo-7f3a9c2e1b
+                      roleArn: arn:aws:iam::123456789012:role/celigo-http-adaptor-orders
         '400':
           $ref: '#/components/responses/400-bad-request'
         '401':
@@ -199,7 +222,38 @@ paths:
         '403':
           $ref: '#/components/responses/403-forbidden'
         '422':
-          $ref: '#/components/responses/422-unprocessable-entity'
+          description: |-
+            Unprocessable entity. The body was well-formed but the provider's credential
+            sub-object is missing or invalid.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+              examples:
+                awsIamSubSchemaMissing:
+                  summary: awsIam provider without the awsIam object
+                  value:
+                    errors:
+                      - field: awsIam
+                        code: missing_required_field
+                        message: The awsIam sub-schema is required
+                      - field: awsIam.externalId
+                        code: missing_required_field
+                        message: 'Expected field: externalId to be present.'
+                awsIamExternalIdInvalid:
+                  summary: externalId outside the allowed character set
+                  value:
+                    errors:
+                      - field: awsIam.externalId
+                        code: invalid_field_value
+                        message: externalId must be 2-1224 characters and contain only alphanumeric and +=,.@:/_- characters.
+                awsIamRoleArnInvalid:
+                  summary: roleArn is not an IAM role ARN
+                  value:
+                    errors:
+                      - field: awsIam.roleArn
+                        code: invalid_field_value
+                        message: roleArn must match format arn:aws:iam::{account-id}:role/[path/]{role-name}.
   /v1/iclients/{_id}:
     get:
       x-internal: false
@@ -3947,23 +4001,44 @@ components:
         awsIam:
           type: object
           description: |-
-            AWS IAM cross-account role credentials. Required when `provider` is `awsIam`.
-            Celigo assumes `roleArn` using `externalId` as the trust-policy external ID.
+            AWS IAM cross-account role credentials. Required when `provider` is `awsIam`
+            (omitting the object fails with 422 `missing_required_field` "The awsIam sub-schema is
+            required"). Celigo assumes `roleArn` using `externalId` as the trust-policy external ID.
+            The iClient itself saves with `externalId` alone; the connection that references it
+            adds its own rules on `roleArn` (see that field).
           required:
             - externalId
           properties:
             externalId:
               type: string
+              minLength: 2
+              maxLength: 1224
+              pattern: ^[a-zA-Z0-9+=,.@:/_-]+$
               description: |-
                 External ID Celigo presents when assuming the role; must match the
-                `sts:ExternalId` condition in the role's trust policy.
+                `sts:ExternalId` condition in the role's trust policy. Fixed at creation: a `PUT`
+                that sends a different value keeps the stored one. A value outside the allowed
+                character set or length fails with 422 `invalid_field_value`.
               examples:
                 - celigo-7f3a9c2e1b
             roleArn:
               type: string
-              description: ARN of the AWS IAM role to assume for cross-account access.
+              pattern: ^arn:[a-z-]+:iam::\d{12}:role/[A-Za-z0-9+=,.@_/-]{1,576}$
+              description: |-
+                ARN of the AWS IAM role to assume for cross-account access. Optional on the iClient
+                (a malformed ARN fails with 422 `invalid_field_value`), but an HTTP connection with
+                `auth.type` `awsiam` cannot be saved against this iClient until it is set and its
+                role name starts with `celigo-http-adaptor-`.
+              x-celigo-ai-guidance:
+                - |-
+                  For an HTTP connection using auth.type "awsiam", name the role
+                  "celigo-http-adaptor-<anything>" — the connection save fails with 422
+                  invalid_field_value "HTTP IAM Role authentication requires awsIam.roleArn to
+                  reference a role name starting with celigo-http-adaptor-." otherwise, and with 422
+                  missing_required_field "Expected field: awsIam.roleArn to be present." while roleArn
+                  is unset. The prefix rule is specific to HTTP awsiam connections.
               examples:
-                - arn:aws:iam::123456789012:role/celigo-integration
+                - arn:aws:iam::123456789012:role/celigo-http-adaptor-orders
         jwt:
           type: object
           description: |-
@@ -4078,6 +4153,15 @@ components:
             isSecretBase64Encoded:
               type: boolean
               description: When true, the `secret` value is Base64-encoded.
+      if:
+        properties:
+          provider:
+            const: awsIam
+        required:
+          - provider
+      then:
+        required:
+          - awsIam
     ResourceResponse:
       type: object
       description: Response
@@ -4199,7 +4283,8 @@ components:
       description: |-
         iClient configuration. The shape varies by `provider` — each provider
         requires its own credential sub-object (`oauth2`, `netsuite`,
-        `salesforce`, `ebay`, `amazonmws`, `azureserviceprincipal`).
+        `salesforce`, `ebay`, `amazonmws`, `azureserviceprincipal`,
+        `googleserviceaccount`, `awsIam`).
         For `custom_oauth2`, credentials go in the `oauth2` sub-object.
         Secrets (`clientSecret`, `privateKey`, etc.) are returned masked
         as `"******"`. On update, re-send that masked value to keep the
@@ -4262,6 +4347,13 @@ components:
           description: Display name of the dependent resource.
           examples:
             - Import Orders to NetSuite
+        type:
+          type: string
+          description: |-
+            Sub-type of the dependent resource when its collection distinguishes one, such as
+            `stream` for a listener export. Only present for resource types that carry a `type`.
+          examples:
+            - stream
         paths:
           type: array
           description: |-
@@ -4385,9 +4477,9 @@ components:
                 errors:
                   - code: forbidden
                     message: You do not have permission to access this resource.
-    422-unprocessable-entity:
+    404-not-found:
       description: |
-        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+        Not found. The requested resource does not exist or is not visible to the caller.
       content:
         application/json:
           schema:
@@ -4396,11 +4488,11 @@ components:
             default:
               value:
                 errors:
-                  - code: unprocessable_entity
-                    message: The request could not be processed due to a semantic error.
-    404-not-found:
+                  - code: not_found
+                    message: The requested resource was not found.
+    422-unprocessable-entity:
       description: |
-        Not found. The requested resource does not exist or is not visible to the caller.
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
       content:
         application/json:
           schema:
@@ -4409,7 +4501,7 @@ components:
             default:
               value:
                 errors:
-                  - code: not_found
-                    message: The requested resource was not found.
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
 x-enable-proxy: true
 x-internal: false