@celigo/api-specs 0.2.153 → 0.2.154

package/dist/api.yml

@@ -5258,7 +5258,7 @@ components:
                 connection's traffic counts against the referenced connection's limit instead of its own,
                 and its own concurrency and auto-recovery settings have no effect. One level only: the
                 referenced connection may not itself borrow, and a connection that others borrow from
-                cannot start borrowing.
+                cannot start borrowing. A connection cannot reference itself (422).
               examples:
                 - 615dfa0742763671275b70ab
               x-celigo-ai-guidance:
@@ -5295,16 +5295,21 @@ components:
               type: boolean
               description: |-
                 When true, the connection has been taken offline and is skipped during flow execution.
-                The platform tests the connection after a create or `PUT` and updates this shortly
-                afterwards (the audit log records a `system` change; `lastModified` doesn't move), so
-                read it again a few seconds after the write.
+                It is set by the connection test a create or `PUT` runs: the result arrives in the
+                write's response or, when the target is slow to answer, shortly afterwards (the audit
+                log records a `system` change; `lastModified` doesn't move), so read it again a few
+                seconds after the write. On an `http` connection the write runs the test only when
+                `http.ping` is configured, and an `http` connection that was never tested has no
+                `offline` key.
               readOnly: true
             needsAuthorization:
               type: boolean
               readOnly: true
               description: |-
                 OAuth handshake state. Celigo's OAuth callback sets it to `false` once the user consents
-                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`).
+                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`). A connection that
+                was never authorized usually has no `needsAuthorization` key, so its absence does not
+                mean the connection is authorized.
             _sourceId:
               type: string
               format: objectId
@@ -6279,15 +6284,18 @@ components:
         clientId:
           type: string
           description: |
-            OAuth client ID (application ID) registered with the API provider.
-            Required for all OAuth 2.0 grant types.
+            OAuth client ID (application ID) registered with the API provider. An `http`
+            connection takes the app from a `custom_oauth2` iClient referenced by `http._iClientId`
+            (an `mcp` connection from `mcp.http._iClientId`) and doesn't store this field: a create
+            that sends `clientId` and `clientSecret` here answers 201 without either (and stores
+            `useIClientFields: true` unless `false` is sent).
           examples:
             - 0oa1b2c3d4EXAMPLE5
         clientSecret:
           type: string
           description: |
-            OAuth client secret (encrypted at rest).
-            Required for "authorizecode" and "clientcredentials" grant types.
+            OAuth client secret (encrypted at rest). Not stored on an `http` connection: the secret
+            belongs on the iClient (see `clientId`).
           writeOnly: true
           examples:
             - cs_abc123EXAMPLE456secret
@@ -6503,9 +6511,11 @@ components:
           - "authorizecode" — Authorization Code flow (browser-based user consent).
             Requires authURI, tokenURI, and user authorization via browser.
           - "clientcredentials" — Client Credentials flow (server-to-server, no user).
-            Requires tokenURI, clientId, clientSecret.
+            Requires tokenURI.
           - "password" — Resource Owner Password flow (username/password exchange).
-            Requires tokenURI, username, password, clientId, clientSecret.
+            Requires tokenURI, username, password.
+          - On an `http` connection the client ID and secret are never stored here: a
+            `custom_oauth2` iClient referenced by `http._iClientId` supplies them.
     JWT:
       type: object
       description: |-

package/dist/connection.yml

@@ -841,6 +841,11 @@ paths:
         `ftp.concurrencyLevel` and `ftp.targetConcurrencyLevel` (the latter is unset whenever
         `autoRecoverRateLimitErrors` is false). `connectionRole` is read-only here: a body carrying
         `mcpChild` is rejected.
+
+        An OAuth connection's `http.auth.oauth.authURI` and `tokenURI` can't change: a body that
+        changes either is rejected with 422 "Updating the value in tokenURI is not allowed for oauth
+        connections due to security reasons. Please contact celigo support." (and the same for
+        `authURI`), and nothing is saved. To move to new OAuth URLs, create a new connection.
       operationId: updateConnection
       tags:
         - Connections
@@ -1028,7 +1033,8 @@ paths:
         borrowed-from connection must exist in the account and may not itself borrow
         (422 `connection_borrows_from_another`), and a connection that others borrow
         from cannot start borrowing (422 `connection_borrowed_by_another`). A
-        connection naming itself is accepted, so check the id before sending it.
+        connection can't borrow from itself: naming its own id is rejected with 422 ("… a
+        connection cannot borrow concurrency from itself."), here and on `PUT`.
         Settings-only changes are recorded in the connection's audit log.
       operationId: patchConnection
       tags:
@@ -1134,6 +1140,15 @@ paths:
         Deletes a connection. The connection is soft-deleted and retained in the
         recycle bin for 30 days before permanent removal. Use
         `POST /v1/recycleBinTTL/connections/{_id}` to restore it during that window.
+
+        Rejected with 422 while anything still uses the connection; the message names each
+        blocker — every export or import on it, the flows they are steps of, and any connection
+        whose `_borrowConcurrencyFromConnectionId` points at it (clearing that field is enough).
+        Registration on an integration does not block the delete, and neither do exports, imports
+        or flows already in the recycle bin; but purging the connection early
+        (`DELETE /v1/recycleBinTTL/connections/{_id}`) is rejected with 422 "this document is
+        referenced by Export : …" while a binned export or import still points at it, so purge the
+        flows, then the exports and imports, then the connection.
       operationId: deleteConnection
       tags:
         - Connections
@@ -1161,7 +1176,7 @@ paths:
         - |-
           Soft-deletes the connection into the recycle bin (restorable for 30 days). Check
           `GET /v1/connections/{_id}/dependencies` first — a connection still referenced by flows,
-          exports, or imports is rejected with 422.
+          exports, imports, or a borrowing connection is rejected with 422.
   /v1/connections/{_id}/ping:
     get:
       x-internal: false
@@ -1170,7 +1185,8 @@ paths:
         GET variant of the saved-connection ping — identical behavior to
         `POST /v1/connections/{_id}/ping`, with no request body to send. Runs the adaptor's ping
         routine against the connection identified by `_id` to verify its credentials and network
-        configuration still work; no data is read, written, or modified.
+        configuration still work; no data is read, written, or modified. An `http` connection with
+        no `http.ping` answers `{code: 200}` without sending any request.
 
         Inspect the response body, not the HTTP status, to determine the outcome: success and
         adaptor-level failures both return HTTP 200 — success is `{code: 200}`, failures are
@@ -1243,16 +1259,20 @@ paths:
           Behaves identically to POST /v1/connections/{_id}/ping and takes no request body — use
           whichever verb the client supports. Both verbs return HTTP 200 with {code: 200} on
           success and HTTP 200 with {errors: [...]} on adaptor-level failure, so inspect the body,
-          not the status code.
+          not the status code. On an `http` connection, {code: 200} shows reachability only once
+          `http.ping` is set: with no ping configured, nothing is sent and the answer is always
+          {code: 200}.
     post:
       x-internal: false
       summary: Ping an existing connection
       description: |-
         Runs the adaptor's ping routine against a saved connection to verify its credentials and
         network configuration still work; no data is read, written, or modified. The check is
-        adaptor-specific (HTTP runs the ping relativeURI or baseURI, RDBMS/JDBC open a driver
-        session, MCP issues a tools/list, NetSuite/Salesforce do a token or session validation).
-        The request body is optional and ignored.
+        adaptor-specific (HTTP sends the `http.ping` request, RDBMS/JDBC open a driver session,
+        MCP issues a tools/list, NetSuite/Salesforce do a token or session validation). An `http`
+        connection with no `http.ping` passes with `{code: 200}` without sending any request, so
+        the ping proves nothing about it until a ping is configured. The request body is optional
+        and ignored.
 
         Inspect the response body, not the HTTP status, to determine the outcome: success and
         adaptor-level failures both return HTTP 200 — success is `{code: 200}`, failures are
@@ -1362,6 +1382,10 @@ paths:
           - Test network connectivity
           - Verify permissions for basic operations
           - Return connection status and any error details
+
+          Exception: an `http` connection with no `http.ping` answers {code: 200} without sending
+          any request, so it proves nothing until a ping (ideally one that needs the connection's
+          credentials) is configured.
   /v1/connections/{_id}/proxy:
     post:
       x-internal: false
@@ -2452,6 +2476,9 @@ paths:
         The response is a plain-text stream (not JSON): each entry is a header line
         (`timestamp traceKey resourceType resourceId`) followed by a single-line JSON payload,
         entries separated by blank lines; paired request/response entries share a `traceKey`.
+        A response payload carries only `headers` and `body` — no HTTP status code, so judge a
+        failure by the body and by headers such as `Retry-After`. Connection tests are logged too:
+        resource type `ping` with an empty `resourceId`, and `isPing: true` in the request payload.
         Logs are shared across every flow using the connection (filter by `resourceId` client-side),
         and sensitive header values are redacted (`"Authorization": "********"`). For execution logs
         tied to a specific run, use `GET /v1/flows/{_id}/jobs/{_jobId}/logs` instead.
@@ -2916,6 +2943,13 @@ paths:
         `/v1/connections/{_id}/oauth2` is an alias that answers identically. The URL's
         `state` token is one-time and expires quickly, so request a fresh one if the flow is
         interrupted, then poll `GET /v1/connections/{_id}` until `needsAuthorization` is `false`.
+
+        The URL's `redirect_uri` is the account's Celigo callback
+        (`https://integrator.io/connection/oauth2callback` on North America), which the provider's
+        app registration must list. On an `http` connection the client comes from the iClient in
+        `http._iClientId`: with no iClient the request is rejected with 422 `unknown http authURI`,
+        and an iClient whose `oauth2.validDomainNames` lacks the authorization URL's registrable
+        domain is rejected as well (see the 422 examples).
       parameters:
         - name: _id
           in: path
@@ -2959,9 +2993,11 @@ paths:
           $ref: '#/components/responses/404-not-found'
         '422':
           description: |-
-            Connection exists but is not configured for OAuth — e.g. an FTP, S3, or plain-auth
-            HTTP connection. The server fails the handshake pre-check because the connection has
-            no `authURI` in its config.
+            The handshake pre-check failed: the connection has no `authURI` in its config (an FTP,
+            S3, plain-auth or client-credentials HTTP connection — nothing to authorize in a
+            browser); an `http` connection has no iClient (`unknown http authURI: "<registrable
+            domain>"`); or its iClient's `oauth2.validDomainNames` doesn't list the authorization
+            URL's registrable domain.
           content:
             application/json:
               schema:
@@ -2974,6 +3010,16 @@ paths:
                       - code: missing_required_field
                         message: 'Expected field: authURI in the Connection to be present.'
                         source: connector
+                noIClient:
+                  summary: HTTP connection with no iClient
+                  value:
+                    errors:
+                      - message: 'unknown http authURI: "example.com"'
+                domainNotListed:
+                  summary: The iClient's validDomainNames lacks the authorization URL's domain
+                  value:
+                    errors:
+                      - message: The domain of request url should be present in iClient.oauth2.validDomainNames
   /v1/connections/{_id}/dependencies:
     get:
       x-internal: false
@@ -4088,7 +4134,7 @@ components:
                 connection's traffic counts against the referenced connection's limit instead of its own,
                 and its own concurrency and auto-recovery settings have no effect. One level only: the
                 referenced connection may not itself borrow, and a connection that others borrow from
-                cannot start borrowing.
+                cannot start borrowing. A connection cannot reference itself (422).
               examples:
                 - 615dfa0742763671275b70ab
               x-celigo-ai-guidance:
@@ -4125,16 +4171,21 @@ components:
               type: boolean
               description: |-
                 When true, the connection has been taken offline and is skipped during flow execution.
-                The platform tests the connection after a create or `PUT` and updates this shortly
-                afterwards (the audit log records a `system` change; `lastModified` doesn't move), so
-                read it again a few seconds after the write.
+                It is set by the connection test a create or `PUT` runs: the result arrives in the
+                write's response or, when the target is slow to answer, shortly afterwards (the audit
+                log records a `system` change; `lastModified` doesn't move), so read it again a few
+                seconds after the write. On an `http` connection the write runs the test only when
+                `http.ping` is configured, and an `http` connection that was never tested has no
+                `offline` key.
               readOnly: true
             needsAuthorization:
               type: boolean
               readOnly: true
               description: |-
                 OAuth handshake state. Celigo's OAuth callback sets it to `false` once the user consents
-                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`).
+                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`). A connection that
+                was never authorized usually has no `needsAuthorization` key, so its absence does not
+                mean the connection is authorized.
             _sourceId:
               type: string
               format: objectId
@@ -5109,15 +5160,18 @@ components:
         clientId:
           type: string
           description: |
-            OAuth client ID (application ID) registered with the API provider.
-            Required for all OAuth 2.0 grant types.
+            OAuth client ID (application ID) registered with the API provider. An `http`
+            connection takes the app from a `custom_oauth2` iClient referenced by `http._iClientId`
+            (an `mcp` connection from `mcp.http._iClientId`) and doesn't store this field: a create
+            that sends `clientId` and `clientSecret` here answers 201 without either (and stores
+            `useIClientFields: true` unless `false` is sent).
           examples:
             - 0oa1b2c3d4EXAMPLE5
         clientSecret:
           type: string
           description: |
-            OAuth client secret (encrypted at rest).
-            Required for "authorizecode" and "clientcredentials" grant types.
+            OAuth client secret (encrypted at rest). Not stored on an `http` connection: the secret
+            belongs on the iClient (see `clientId`).
           writeOnly: true
           examples:
             - cs_abc123EXAMPLE456secret
@@ -5333,9 +5387,11 @@ components:
           - "authorizecode" — Authorization Code flow (browser-based user consent).
             Requires authURI, tokenURI, and user authorization via browser.
           - "clientcredentials" — Client Credentials flow (server-to-server, no user).
-            Requires tokenURI, clientId, clientSecret.
+            Requires tokenURI.
           - "password" — Resource Owner Password flow (username/password exchange).
-            Requires tokenURI, username, password, clientId, clientSecret.
+            Requires tokenURI, username, password.
+          - On an `http` connection the client ID and secret are never stored here: a
+            `custom_oauth2` iClient referenced by `http._iClientId` supplies them.
     JWT:
       type: object
       description: |-
@@ -9560,7 +9616,7 @@ components:
             connection's traffic counts against the referenced connection's limit instead of its own,
             and its own concurrency and auto-recovery settings have no effect. One level only: the
             referenced connection may not itself borrow, and a connection that others borrow from
-            cannot start borrowing.
+            cannot start borrowing. A connection cannot reference itself (422).
           examples:
             - 615dfa0742763671275b70ab
           x-celigo-ai-guidance:

package/dist/enduser.yml

@@ -2200,7 +2200,7 @@ components:
                 connection's traffic counts against the referenced connection's limit instead of its own,
                 and its own concurrency and auto-recovery settings have no effect. One level only: the
                 referenced connection may not itself borrow, and a connection that others borrow from
-                cannot start borrowing.
+                cannot start borrowing. A connection cannot reference itself (422).
               examples:
                 - 615dfa0742763671275b70ab
               x-celigo-ai-guidance:
@@ -2237,16 +2237,21 @@ components:
               type: boolean
               description: |-
                 When true, the connection has been taken offline and is skipped during flow execution.
-                The platform tests the connection after a create or `PUT` and updates this shortly
-                afterwards (the audit log records a `system` change; `lastModified` doesn't move), so
-                read it again a few seconds after the write.
+                It is set by the connection test a create or `PUT` runs: the result arrives in the
+                write's response or, when the target is slow to answer, shortly afterwards (the audit
+                log records a `system` change; `lastModified` doesn't move), so read it again a few
+                seconds after the write. On an `http` connection the write runs the test only when
+                `http.ping` is configured, and an `http` connection that was never tested has no
+                `offline` key.
               readOnly: true
             needsAuthorization:
               type: boolean
               readOnly: true
               description: |-
                 OAuth handshake state. Celigo's OAuth callback sets it to `false` once the user consents
-                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`).
+                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`). A connection that
+                was never authorized usually has no `needsAuthorization` key, so its absence does not
+                mean the connection is authorized.
             _sourceId:
               type: string
               format: objectId
@@ -3221,15 +3226,18 @@ components:
         clientId:
           type: string
           description: |
-            OAuth client ID (application ID) registered with the API provider.
-            Required for all OAuth 2.0 grant types.
+            OAuth client ID (application ID) registered with the API provider. An `http`
+            connection takes the app from a `custom_oauth2` iClient referenced by `http._iClientId`
+            (an `mcp` connection from `mcp.http._iClientId`) and doesn't store this field: a create
+            that sends `clientId` and `clientSecret` here answers 201 without either (and stores
+            `useIClientFields: true` unless `false` is sent).
           examples:
             - 0oa1b2c3d4EXAMPLE5
         clientSecret:
           type: string
           description: |
-            OAuth client secret (encrypted at rest).
-            Required for "authorizecode" and "clientcredentials" grant types.
+            OAuth client secret (encrypted at rest). Not stored on an `http` connection: the secret
+            belongs on the iClient (see `clientId`).
           writeOnly: true
           examples:
             - cs_abc123EXAMPLE456secret
@@ -3445,9 +3453,11 @@ components:
           - "authorizecode" — Authorization Code flow (browser-based user consent).
             Requires authURI, tokenURI, and user authorization via browser.
           - "clientcredentials" — Client Credentials flow (server-to-server, no user).
-            Requires tokenURI, clientId, clientSecret.
+            Requires tokenURI.
           - "password" — Resource Owner Password flow (username/password exchange).
-            Requires tokenURI, username, password, clientId, clientSecret.
+            Requires tokenURI, username, password.
+          - On an `http` connection the client ID and secret are never stored here: a
+            `custom_oauth2` iClient referenced by `http._iClientId` supplies them.
     JWT:
       type: object
       description: |-

package/dist/iclient.yml

@@ -491,6 +491,8 @@ paths:
         Permanently deletes an iClient. Blocked while any connection references
         it, including a deleted connection still in the recycle bin: purge that
         connection with `DELETE /v1/recycleBinTTL/connections/{_id}` first.
+        `GET /v1/iclients/{_id}/dependencies` doesn't list a binned connection,
+        so an empty dependency list doesn't mean the delete will succeed.
       operationId: deleteIClient
       tags:
         - iClients
@@ -1623,68 +1625,12 @@ components:
                 endpoint response body.
               x-celigo-ai-guidance:
                 - |-
-                  ## FIELD BEHAVIOR:
-                  - Defines the endpoint path for access token requests in the OAuth2 flow.
-                  - Must be a valid relative URL path starting with a forward slash (/).
-                  - Used during the token exchange phase after obtaining an authorization code or other grant types.
-                  - Typically combined with the authorization server's base URL to form the complete token endpoint URL.
-                - |-
-                  Specifies the relative URL path on the OAuth2 authorization server where the
-                  access token request should be sent.
-                  This path is appended to the base URL of the authorization server to form the
-                  full endpoint for obtaining an access token during the OAuth2 authentication
-                  flow.
-                  It is essential for enabling clients to exchange authorization grants for access
-                  tokens securely.
-                - |-
-                  ## IMPORTANT NOTES:
-                  - This path is critical for the OAuth2 token exchange process; incorrect configuration will prevent successful authentication.
-                  - It should not include the full URL, only the path component.
-                  - Must align with the OAuth2 server's documentation to ensure interoperability.
-                  - Often used in conjunction with other OAuth2 properties like client ID, client secret, and authorization path.
-                - |-
-                  ## DEPENDENCY CHAIN:
-                  - Depends on the base URL of the OAuth2 authorization server.
-                  - Used alongside authorizationPath and other OAuth2 configuration properties.
-                  - Integral to the OAuth2 token grant process.
-                - |-
-                  ## EXAMPLES:
-                  - /oauth2/token
-                  - /api/v1/access_token
-                  - /auth/token
-                - |-
-                  ## IMPLEMENTATION GUIDANCE:
-                  - Ensure the path corresponds exactly to the OAuth2 server's token endpoint specification.
-                  - Validate that the path is correctly formatted and accessible.
-                  - Avoid including query parameters or fragments in this path; it should be a clean URL path.
-                  - Confirm compatibility with the OAuth2 server's expected token endpoint URL structure.
-                - |-
-                  ## TECHNICAL DETAILS:
-                  - Expected to be a URI path string.
-                  - Should begin with a forward slash (/).
-                  - Combined with the OAuth2 server's base URL to form the full token endpoint URI.
-                  - Utilized in HTTP POST requests to obtain access tokens.
-                - |-
-                  Specifies the relative URL path on the OAuth2 authorization server where the
-                  access token request should be sent.
-                  This path is appended to the base URL of the authorization server to form the
-                  full endpoint for obtaining an access token during the OAuth2 authentication
-                  flow.
-                  It is essential for enabling clients to exchange authorization grants for access
-                  tokens securely.
-                - |-
-                  Specifies the relative URL path on the OAuth2 authorization server where the
-                  access token request should be sent.
-                  This path is appended to the base URL of the authorization server to form the
-                  full endpoint for obtaining an access token during the OAuth2 authentication
-                  flow.
-                  It is essential for enabling clients to exchange authorization grants for access
-                  tokens securely.
+                  A path into the token endpoint's JSON response — `access_token`, or
+                  `data.access_token` when the provider nests it — never a URL or an endpoint path.
+                  The token endpoint itself is `token.uri`.
               examples:
                 - access_token
-                - /oauth2/token
-                - /api/v1/access_token
-                - /auth/token
+                - data.access_token
             refreshTokenPath:
               type: string
               description: |-
@@ -1692,72 +1638,12 @@ components:
                 endpoint response body.
               x-celigo-ai-guidance:
                 - |-
-                  ## IMPORTANT NOTES:
-                  - This path is distinct from the initial token request endpoint.
-                  - The refresh token flow requires that the client has previously obtained a refresh token.
-                  - Not all OAuth 2.0 providers support refresh tokens; verify compatibility.
-                  - The endpoint must support secure communication protocols (e.g., HTTPS).
-                - |-
-                  ## EXAMPLES:
-                  - "/oauth2/token/refresh"
-                  - "https://auth.example.com/oauth2/token"
-                  - "/api/v1/auth/refresh-token"
-                - |-
-                  ## DEPENDENCY CHAIN:
-                  - Depends on the existence of a valid refresh token issued during initial authentication.
-                  - Works in conjunction with the access token and client credentials.
-                  - Related to the OAuth 2.0 token endpoint configuration.
-                - |-
-                  The relative or absolute URL path used to request a refresh token from the OAuth
-                  2.0 authorization server.
-                  This endpoint is typically called when the current access token has expired or
-                  is about to expire,
-                  allowing the client to obtain a new access token without requiring the user to re-authenticate.
-                  The path should conform to the OAuth 2.0 specification for token refresh
-                  requests and support the necessary HTTP methods,
-                  usually POST.
-                - |-
-                  ## TECHNICAL DETAILS:
-                  - Typically uses the HTTP POST method with form-encoded parameters.
-                  - Requires parameters such as grant_type=refresh_token and the refresh_token itself.
-                  - Responses include a new access token and optionally a new refresh token.
-                  - Must handle scopes and token expiration as per OAuth 2.0 standards.
-                - |-
-                  ## IMPLEMENTATION GUIDANCE:
-                  - Ensure the path is correctly formatted as a relative or absolute URL.
-                  - Confirm that the authorization server supports refresh token requests at this endpoint.
-                  - Secure the endpoint with appropriate authentication and authorization measures.
-                  - Validate that the client credentials and refresh token are correctly handled during the request.
-                  - Handle error responses gracefully, such as invalid or expired refresh tokens.
-                - |-
-                  ## FIELD BEHAVIOR:
-                  - Specifies the endpoint for refreshing OAuth 2.0 access tokens.
-                  - Used by the client application to maintain authenticated sessions seamlessly.
-                  - Invoked automatically by the client when the access token expires or is near expiration.
-                  - Must be accessible and correctly configured on the authorization server.
-                - |-
-                  The relative or absolute URL path used to request a refresh token from the OAuth
-                  2.0 authorization server.
-                  This endpoint is typically called when the current access token has expired or
-                  is about to expire,
-                  allowing the client to obtain a new access token without requiring the user to re-authenticate.
-                  The path should conform to the OAuth 2.0 specification for token refresh
-                  requests and support the necessary HTTP methods,
-                  usually POST.
-                - |-
-                  The relative or absolute URL path used to request a refresh token from the OAuth
-                  2.0 authorization server.
-                  This endpoint is typically called when the current access token has expired or
-                  is about to expire,
-                  allowing the client to obtain a new access token without requiring the user to re-authenticate.
-                  The path should conform to the OAuth 2.0 specification for token refresh
-                  requests and support the necessary HTTP methods,
-                  usually POST.
+                  A path into the token endpoint's JSON response — `refresh_token`, or
+                  `data.refresh_token` when the provider nests it — never a URL or an endpoint path.
+                  The refresh endpoint itself is `refresh.uri`.
               examples:
                 - refresh_token
-                - /oauth2/token/refresh
-                - https://auth.example.com/oauth2/token
-                - /api/v1/auth/refresh-token
+                - data.refresh_token
             scheme:
               type: string
               description: Authorization scheme prefix (e.g. `Bearer`, `Basic`).

package/dist/mcp-server.yml

@@ -4031,7 +4031,7 @@ components:
                 connection's traffic counts against the referenced connection's limit instead of its own,
                 and its own concurrency and auto-recovery settings have no effect. One level only: the
                 referenced connection may not itself borrow, and a connection that others borrow from
-                cannot start borrowing.
+                cannot start borrowing. A connection cannot reference itself (422).
               examples:
                 - 615dfa0742763671275b70ab
               x-celigo-ai-guidance:
@@ -4068,16 +4068,21 @@ components:
               type: boolean
               description: |-
                 When true, the connection has been taken offline and is skipped during flow execution.
-                The platform tests the connection after a create or `PUT` and updates this shortly
-                afterwards (the audit log records a `system` change; `lastModified` doesn't move), so
-                read it again a few seconds after the write.
+                It is set by the connection test a create or `PUT` runs: the result arrives in the
+                write's response or, when the target is slow to answer, shortly afterwards (the audit
+                log records a `system` change; `lastModified` doesn't move), so read it again a few
+                seconds after the write. On an `http` connection the write runs the test only when
+                `http.ping` is configured, and an `http` connection that was never tested has no
+                `offline` key.
               readOnly: true
             needsAuthorization:
               type: boolean
               readOnly: true
               description: |-
                 OAuth handshake state. Celigo's OAuth callback sets it to `false` once the user consents
-                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`).
+                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`). A connection that
+                was never authorized usually has no `needsAuthorization` key, so its absence does not
+                mean the connection is authorized.
             _sourceId:
               type: string
               format: objectId
@@ -5052,15 +5057,18 @@ components:
         clientId:
           type: string
           description: |
-            OAuth client ID (application ID) registered with the API provider.
-            Required for all OAuth 2.0 grant types.
+            OAuth client ID (application ID) registered with the API provider. An `http`
+            connection takes the app from a `custom_oauth2` iClient referenced by `http._iClientId`
+            (an `mcp` connection from `mcp.http._iClientId`) and doesn't store this field: a create
+            that sends `clientId` and `clientSecret` here answers 201 without either (and stores
+            `useIClientFields: true` unless `false` is sent).
           examples:
             - 0oa1b2c3d4EXAMPLE5
         clientSecret:
           type: string
           description: |
-            OAuth client secret (encrypted at rest).
-            Required for "authorizecode" and "clientcredentials" grant types.
+            OAuth client secret (encrypted at rest). Not stored on an `http` connection: the secret
+            belongs on the iClient (see `clientId`).
           writeOnly: true
           examples:
             - cs_abc123EXAMPLE456secret
@@ -5276,9 +5284,11 @@ components:
           - "authorizecode" — Authorization Code flow (browser-based user consent).
             Requires authURI, tokenURI, and user authorization via browser.
           - "clientcredentials" — Client Credentials flow (server-to-server, no user).
-            Requires tokenURI, clientId, clientSecret.
+            Requires tokenURI.
           - "password" — Resource Owner Password flow (username/password exchange).
-            Requires tokenURI, username, password, clientId, clientSecret.
+            Requires tokenURI, username, password.
+          - On an `http` connection the client ID and secret are never stored here: a
+            `custom_oauth2` iClient referenced by `http._iClientId` supplies them.
     JWT:
       type: object
       description: |-

package/dist/tool.yml

@@ -7482,7 +7482,7 @@ components:
                 connection's traffic counts against the referenced connection's limit instead of its own,
                 and its own concurrency and auto-recovery settings have no effect. One level only: the
                 referenced connection may not itself borrow, and a connection that others borrow from
-                cannot start borrowing.
+                cannot start borrowing. A connection cannot reference itself (422).
               examples:
                 - 615dfa0742763671275b70ab
               x-celigo-ai-guidance:
@@ -7519,16 +7519,21 @@ components:
               type: boolean
               description: |-
                 When true, the connection has been taken offline and is skipped during flow execution.
-                The platform tests the connection after a create or `PUT` and updates this shortly
-                afterwards (the audit log records a `system` change; `lastModified` doesn't move), so
-                read it again a few seconds after the write.
+                It is set by the connection test a create or `PUT` runs: the result arrives in the
+                write's response or, when the target is slow to answer, shortly afterwards (the audit
+                log records a `system` change; `lastModified` doesn't move), so read it again a few
+                seconds after the write. On an `http` connection the write runs the test only when
+                `http.ping` is configured, and an `http` connection that was never tested has no
+                `offline` key.
               readOnly: true
             needsAuthorization:
               type: boolean
               readOnly: true
               description: |-
                 OAuth handshake state. Celigo's OAuth callback sets it to `false` once the user consents
-                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`).
+                and the tokens are stored (see `GET /v1/connection/{_id}/oauth2`). A connection that
+                was never authorized usually has no `needsAuthorization` key, so its absence does not
+                mean the connection is authorized.
             _sourceId:
               type: string
               format: objectId
@@ -8503,15 +8508,18 @@ components:
         clientId:
           type: string
           description: |
-            OAuth client ID (application ID) registered with the API provider.
-            Required for all OAuth 2.0 grant types.
+            OAuth client ID (application ID) registered with the API provider. An `http`
+            connection takes the app from a `custom_oauth2` iClient referenced by `http._iClientId`
+            (an `mcp` connection from `mcp.http._iClientId`) and doesn't store this field: a create
+            that sends `clientId` and `clientSecret` here answers 201 without either (and stores
+            `useIClientFields: true` unless `false` is sent).
           examples:
             - 0oa1b2c3d4EXAMPLE5
         clientSecret:
           type: string
           description: |
-            OAuth client secret (encrypted at rest).
-            Required for "authorizecode" and "clientcredentials" grant types.
+            OAuth client secret (encrypted at rest). Not stored on an `http` connection: the secret
+            belongs on the iClient (see `clientId`).
           writeOnly: true
           examples:
             - cs_abc123EXAMPLE456secret
@@ -8727,9 +8735,11 @@ components:
           - "authorizecode" — Authorization Code flow (browser-based user consent).
             Requires authURI, tokenURI, and user authorization via browser.
           - "clientcredentials" — Client Credentials flow (server-to-server, no user).
-            Requires tokenURI, clientId, clientSecret.
+            Requires tokenURI.
           - "password" — Resource Owner Password flow (username/password exchange).
-            Requires tokenURI, username, password, clientId, clientSecret.
+            Requires tokenURI, username, password.
+          - On an `http` connection the client ID and secret are never stored here: a
+            `custom_oauth2` iClient referenced by `http._iClientId` supplies them.
     JWT:
       type: object
       description: |-

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celigo/api-specs",
-  "version": "0.2.153",
+  "version": "0.2.154",
   "private": false,
   "description": "Public OpenAPI bundles (dist/) and the celigo-cli lint schema pack (schemas.json).",
   "keywords": [

package/schemas.json

@@ -1,7 +1,7 @@
 {
 	"provenance": {
 		"repo": "celigo/integrator-api-specs",
-		"iasCommit": "edaea717",
+		"iasCommit": "6baefd4f",
 		"generatedAt": "2026-10-21"
 	},
 	"roots": {