@celigo/api-specs 0.2.92 → 0.2.94

package/dist/account.yml

@@ -19,12 +19,12 @@ tags:
     description: |-
       Endpoints for discovering what the current account has access to.
 
-      Resolve a bearer token to a user, list the external applications connected
-      to the account, and manage shared accounts and stacks.
+      Resolve a bearer token to the account, credential, and user behind it, list the
+      external applications connected to the account, and manage shared accounts and stacks.
 
-      ## Shared account and stack share schemas
+      ## Token info, shared account and stack share schemas
 
-      {% openapi-schemas spec="account" schemas="SharedAccount,StackShare" grouped="true" %}
+      {% openapi-schemas spec="account" schemas="TokenInfo,SharedAccount,StackShare" grouped="true" %}
 paths:
   /v1/tokenInfo:
     get:
@@ -32,29 +32,79 @@ paths:
       operationId: getTokenInfo
       tags:
         - Account
-      summary: Identify the current token's owner
-      description: Resolves a bearer token to the user it authenticates as.
+      summary: Resolve the current token's identity
+      description: |-
+        Resolves the bearer token on the request to the account it belongs to, the credential it
+        is, the user acting through it, and the environment it is bound to. Call it with the
+        same token you use for other requests — there is no body and no query parameter.
+
+        `token.type` names the credential kind. An account API token (`service`) also reports
+        the acting user in `byUser`; an on-premise agent token (`agent`) acts as the account
+        itself and omits `byUser`.
       responses:
         '200':
-          description: Token identity.
+          description: Token identity envelope.
           content:
             application/json:
               schema:
-                type: object
-                properties:
-                  _userId:
-                    type: string
-                    format: objectId
-                    x-celigo-refModel: users
-                    examples:
-                      - 5e58483b68b52e5827d56a86
-                    description: User this token authenticates as.
+                $ref: '#/components/schemas/TokenInfo'
               examples:
-                default:
+                serviceToken:
+                  summary: Account API token created by the account owner
+                  value:
+                    _userId: 5e58483b68b52e5827d56a86
+                    token:
+                      type: service
+                      _id: 68f5a1b2c3d4e5f678901234
+                      name: ci-deploy-bot
+                      fullAccess: true
+                    ownerUser:
+                      _id: 5e58483b68b52e5827d56a86
+                      email: jane@acme.com
+                      name: Jane Owner
+                      company: Acme Corp
+                    byUser:
+                      _id: 5e58483b68b52e5827d56a86
+                      email: jane@acme.com
+                      name: Jane Owner
+                      accessLevel: owner
+                    environment:
+                      _id: 69f1da72317aa6e158632d9b
+                      name: Production
+                      _envUserId: 5e58483b68b52e5827d56a86
+                agentToken:
+                  summary: On-premise agent token (no byUser, no fullAccess)
                   value:
                     _userId: 5e58483b68b52e5827d56a86
+                    token:
+                      type: agent
+                      _id: 68f5a1b2c3d4e5f678901238
+                      name: warehouse-agent-01
+                    ownerUser:
+                      _id: 5e58483b68b52e5827d56a86
+                      email: jane@acme.com
+                      name: Jane Owner
+                      company: Acme Corp
+                    environment:
+                      _id: 69f1da72317aa6e158632d9b
+                      name: Production
+                      _envUserId: 5e58483b68b52e5827d56a86
         '401':
-          $ref: '#/components/responses/401-unauthorized'
+          description: |-
+            Unauthorized. Unlike other routes, this one answers a missing `Authorization` header
+            and an invalid token the same way: a bare text body `Unauthorized` with no
+            `Content-Type` header and no `{errors: [...]}` or `{message}` JSON envelope. Key off
+            the HTTP status, not the body.
+          content:
+            text/plain:
+              schema:
+                type: string
+                examples:
+                  - Unauthorized
+              examples:
+                unauthorized:
+                  summary: Missing or invalid bearer token
+                  value: Unauthorized
   /v1/applications:
     get:
       x-internal: false
@@ -350,42 +400,160 @@ components:
     bearerAuth:
       type: http
       scheme: bearer
-  responses:
-    401-unauthorized:
+  schemas:
+    TokenInfo:
+      type: object
       description: |-
-        Unauthorized. The request lacks a valid bearer token, or the provided token
-        failed to authenticate.
-
-        Note: the 401 response is produced by the auth middleware **before** the
-        request reaches the endpoint handler, so it does **not** follow the
-        standard `{errors: [...]}` envelope. Instead the body is a bare
-        `{message: string}` object with no `code`, no `errors` array. Callers
-        handling 401s should key off the HTTP status and the `message` string,
-        not try to destructure an `errors[]`.
-      content:
-        application/json:
-          schema:
-            type: object
-            properties:
-              message:
-                type: string
-                description: |-
-                  Human-readable description of the auth failure. Known values:
-                  - `"Unauthorized"` — no `Authorization` header on the request.
-                  - `"Bearer Authentication Failed"` — header present but token
-                    is invalid, revoked, or expired.
-            required:
-              - message
+        Identity envelope for the bearer token on the request: the credential kind, the
+        account owner, the user acting through it, and the environment it is bound to.
+        Read the account id from `ownerUser._id` and the actor from `byUser`; `_userId` is
+        the user record the token is bound to, which for a token on the production
+        environment is the account owner.
+      required:
+        - _userId
+        - token
+        - ownerUser
+      x-celigo-ai-guidance:
+        - |-
+          Use ownerUser._id as the account id and token.type to tell credential kinds apart.
+          byUser is absent on on-premise agent tokens (type agent), so never dereference it
+          without checking the type first.
+      properties:
+        _userId:
+          type: string
+          format: objectId
+          x-celigo-refModel: users
           examples:
-            missing_token:
-              summary: No Authorization header sent
-              value:
-                message: Unauthorized
-            invalid_token:
-              summary: Bearer token invalid or revoked
-              value:
-                message: Bearer Authentication Failed
-  schemas:
+            - 5e58483b68b52e5827d56a86
+          description: |-
+            User record the token is bound to. For a token on the production environment this
+            is the account owner, so it matches both `ownerUser._id` and
+            `environment._envUserId`.
+        token:
+          type: object
+          description: The credential that authenticated the request. Never echoes the secret value.
+          required:
+            - type
+          properties:
+            type:
+              type: string
+              examples:
+                - service
+              description: |-
+                Credential kind: `service` for an account API token, `agent` for an on-premise
+                agent's access token. Read this field rather than inferring the kind from which
+                other fields are present.
+            _id:
+              type: string
+              format: objectId
+              examples:
+                - 68f5a1b2c3d4e5f678901234
+              description: |-
+                Record the credential belongs to: the access token for a `service` token, the
+                on-premise agent (`GET /v1/agents/{_id}`) for an `agent` token.
+            name:
+              type: string
+              examples:
+                - ci-deploy-bot
+              description: |-
+                Display name of the access token for a `service` token; the agent's name for an
+                `agent` token.
+            fullAccess:
+              type: boolean
+              description: |-
+                When true, the token has unrestricted access to the account. Present on `service`
+                tokens only; `agent` tokens omit it.
+        ownerUser:
+          type: object
+          description: Account (tenant) owner. Use `_id` as the account id.
+          required:
+            - _id
+          properties:
+            _id:
+              type: string
+              format: objectId
+              x-celigo-refModel: users
+              examples:
+                - 5e58483b68b52e5827d56a86
+              description: Account owner's user id, which identifies the account itself.
+            email:
+              type: string
+              format: email
+              examples:
+                - jane@acme.com
+              description: Account owner's email address.
+            name:
+              type: string
+              examples:
+                - Jane Owner
+              description: Account owner's display name.
+            company:
+              type: string
+              examples:
+                - Acme Corp
+              description: Company name on the owner's profile.
+        byUser:
+          type: object
+          description: |-
+            User acting through the token. Omitted for `agent` tokens, which act as the account
+            itself. For a `service` token created by the account owner this mirrors `ownerUser`
+            with `accessLevel: owner`.
+          required:
+            - _id
+          properties:
+            _id:
+              type: string
+              format: objectId
+              x-celigo-refModel: users
+              examples:
+                - 5e58483b68b52e5827d56a86
+              description: Acting user's id. Equals `ownerUser._id` when the owner is acting.
+            email:
+              type: string
+              format: email
+              examples:
+                - jane@acme.com
+              description: Acting user's email address.
+            name:
+              type: string
+              examples:
+                - Jane Owner
+              description: Acting user's display name.
+            accessLevel:
+              type: string
+              examples:
+                - owner
+              description: |-
+                Acting user's account-wide access level. `owner` when the acting user is the
+                account owner.
+        environment:
+          type: object
+          description: Environment the token is bound to.
+          required:
+            - name
+          properties:
+            _id:
+              type: string
+              format: objectId
+              x-celigo-refModel: environments
+              examples:
+                - 69f1da72317aa6e158632d9b
+              description: Environment id, as listed by `GET /v1/environments`.
+            name:
+              type: string
+              examples:
+                - Production
+              description: Environment display name.
+            _envUserId:
+              type: string
+              format: objectId
+              x-celigo-refModel: users
+              examples:
+                - 5e58483b68b52e5827d56a86
+              description: |-
+                User record that owns this environment's resources: the account owner for the
+                production environment, a per-environment user for every other environment
+                (the same ids `GET /v1/environments` lists).
     ApplicationUsage:
       type: object
       description: An application and its connections in this account.
@@ -786,5 +954,40 @@ components:
       else:
         required:
           - lambda
+  responses:
+    401-unauthorized:
+      description: |-
+        Unauthorized. The request lacks a valid bearer token, or the provided token
+        failed to authenticate.
+
+        Note: the 401 response is produced by the auth middleware **before** the
+        request reaches the endpoint handler, so it does **not** follow the
+        standard `{errors: [...]}` envelope. Instead the body is a bare
+        `{message: string}` object with no `code`, no `errors` array. Callers
+        handling 401s should key off the HTTP status and the `message` string,
+        not try to destructure an `errors[]`.
+      content:
+        application/json:
+          schema:
+            type: object
+            properties:
+              message:
+                type: string
+                description: |-
+                  Human-readable description of the auth failure. Known values:
+                  - `"Unauthorized"` — no `Authorization` header on the request.
+                  - `"Bearer Authentication Failed"` — header present but token
+                    is invalid, revoked, or expired.
+            required:
+              - message
+          examples:
+            missing_token:
+              summary: No Authorization header sent
+              value:
+                message: Unauthorized
+            invalid_token:
+              summary: Bearer token invalid or revoked
+              value:
+                message: Bearer Authentication Failed
 x-enable-proxy: true
 x-internal: false

package/dist/api.yml

@@ -7365,11 +7365,23 @@ components:
           description: |-
             HTTP connector (pre-built application template) this connection is linked to. Linking
             lets exports and imports on the connection pick endpoints from the connector's catalog and
-            drives the `assistant` form in the UI. An id that does not resolve to an accessible
-            connector is dropped from the saved document rather than rejected — read the response back
-            to confirm the link took.
+            drives the `assistant` form in the UI. The link is resolved server-side on create and on
+            any update that changes `assistant` or a connector id, and the result overwrites
+            `_httpConnectorId`, `_httpConnectorApiId` and `_httpConnectorVersionId`: an id that does
+            not resolve to an accessible connector is dropped rather than rejected, and when the
+            top-level `assistant` names an application with a legacy adaptor (the connector's
+            `legacyId`, e.g. `shopify`) the connector resolved from that slug replaces the id you sent
+            and a sent `_httpConnectorVersionId` is dropped. Read the response back to confirm the
+            link took.
           examples:
             - 5d8f6a2b9c1e4f00112a3b4c
+          x-celigo-ai-guidance:
+            - |-
+              To link an Azure Data Lake Storage Gen2 connection to its connector, send
+              `_httpConnectorId` and `_httpConnectorVersionId` and omit the top-level `assistant`:
+              with `assistant` set (`azuredatalakestoragegen2` or any other slug) the save answers
+              201/200 and stores neither id. Dropping `assistant` and re-sending both ids on a PUT
+              restores the link.
         _httpConnectorApiId:
           type: string
           format: objectId

package/dist/connection.yml

@@ -5972,11 +5972,23 @@ components:
           description: |-
             HTTP connector (pre-built application template) this connection is linked to. Linking
             lets exports and imports on the connection pick endpoints from the connector's catalog and
-            drives the `assistant` form in the UI. An id that does not resolve to an accessible
-            connector is dropped from the saved document rather than rejected — read the response back
-            to confirm the link took.
+            drives the `assistant` form in the UI. The link is resolved server-side on create and on
+            any update that changes `assistant` or a connector id, and the result overwrites
+            `_httpConnectorId`, `_httpConnectorApiId` and `_httpConnectorVersionId`: an id that does
+            not resolve to an accessible connector is dropped rather than rejected, and when the
+            top-level `assistant` names an application with a legacy adaptor (the connector's
+            `legacyId`, e.g. `shopify`) the connector resolved from that slug replaces the id you sent
+            and a sent `_httpConnectorVersionId` is dropped. Read the response back to confirm the
+            link took.
           examples:
             - 5d8f6a2b9c1e4f00112a3b4c
+          x-celigo-ai-guidance:
+            - |-
+              To link an Azure Data Lake Storage Gen2 connection to its connector, send
+              `_httpConnectorId` and `_httpConnectorVersionId` and omit the top-level `assistant`:
+              with `assistant` set (`azuredatalakestoragegen2` or any other slug) the save answers
+              201/200 and stores neither id. Dropping `assistant` and re-sending both ids on a PUT
+              restores the link.
         _httpConnectorApiId:
           type: string
           format: objectId
@@ -8746,9 +8758,24 @@ components:
           type: string
           description: |-
             Lowercase application name for HTTP connections to systems with an integrator.io
-            adaptor (e.g. "shopify", "ebay"). Only applies to http connections.
+            adaptor (e.g. "shopify", "ebay"). Only applies to http connections. The platform
+            checks the slug against its current adaptor list — an unknown value fails the save
+            with 422 `enum` — and uses it to resolve the HTTP connector link on every save (see
+            `http._httpConnectorId`), so send it only when the application really is a legacy
+            adaptor: on an Azure Data Lake Storage Gen2 connection it drops the connector ids.
           examples:
             - shopify
+          x-celigo-ai-guidance:
+            - |-
+              Omit `assistant` on an Azure Data Lake Storage Gen2 connection. With
+              `assistant: "azuredatalakestoragegen2"` (or any other slug) the save answers 201/200
+              but stores no `http._httpConnectorId` or `http._httpConnectorVersionId`; the
+              connection form never sends it. Send the ADLS connector id and version id without
+              `assistant` — a PUT that drops `assistant` and re-sends them restores the link.
+            - |-
+              A value outside the platform's adaptor list fails with 422 `enum` on `assistant`
+              ("`<value>` is not a valid enum value for path `assistant`."); for a connector-framework
+              application with no legacy adaptor, link it through `http._httpConnectorId` instead.
         _agentId:
           type: string
           format: objectId

package/dist/enduser.yml

@@ -4611,11 +4611,23 @@ components:
           description: |-
             HTTP connector (pre-built application template) this connection is linked to. Linking
             lets exports and imports on the connection pick endpoints from the connector's catalog and
-            drives the `assistant` form in the UI. An id that does not resolve to an accessible
-            connector is dropped from the saved document rather than rejected — read the response back
-            to confirm the link took.
+            drives the `assistant` form in the UI. The link is resolved server-side on create and on
+            any update that changes `assistant` or a connector id, and the result overwrites
+            `_httpConnectorId`, `_httpConnectorApiId` and `_httpConnectorVersionId`: an id that does
+            not resolve to an accessible connector is dropped rather than rejected, and when the
+            top-level `assistant` names an application with a legacy adaptor (the connector's
+            `legacyId`, e.g. `shopify`) the connector resolved from that slug replaces the id you sent
+            and a sent `_httpConnectorVersionId` is dropped. Read the response back to confirm the
+            link took.
           examples:
             - 5d8f6a2b9c1e4f00112a3b4c
+          x-celigo-ai-guidance:
+            - |-
+              To link an Azure Data Lake Storage Gen2 connection to its connector, send
+              `_httpConnectorId` and `_httpConnectorVersionId` and omit the top-level `assistant`:
+              with `assistant` set (`azuredatalakestoragegen2` or any other slug) the save answers
+              201/200 and stores neither id. Dropping `assistant` and re-sending both ids on a PUT
+              restores the link.
         _httpConnectorApiId:
           type: string
           format: objectId