@celigo/api-specs 0.2.1

package/dist/account.yml

@@ -0,0 +1,592 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: Account
+  description: API for account-scoped discovery — resolve the current token, list connected applications, and manage shared accounts and stacks.
+servers:
+  - url: https://api.integrator.io
+    description: Production (US / default region)
+  - url: https://api.eu.integrator.io
+    description: Production (EU region)
+  - url: https://api.au.integrator.io
+    description: Production (AU region)
+  - url: https://api.ca.integrator.io
+    description: Production (CA region)
+security:
+  - bearerAuth: []
+tags:
+  - name: Account
+    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.
+
+      ## Shared account and stack share schemas
+
+      {% openapi-schemas spec="account" schemas="SharedAccount,StackShare" grouped="true" %}
+paths:
+  /v1/tokenInfo:
+    get:
+      x-internal: false
+      operationId: getTokenInfo
+      tags:
+        - Account
+      summary: Identify the current token's owner
+      description: Resolves a bearer token to the user it authenticates as.
+      responses:
+        '200':
+          description: Token identity.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  _userId:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: users
+                    examples:
+                      - 5e58483b68b52e5827d56a86
+                    description: User this token authenticates as.
+              examples:
+                default:
+                  value:
+                    _userId: 5e58483b68b52e5827d56a86
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/applications:
+    get:
+      x-internal: false
+      operationId: listAccountApplications
+      tags:
+        - Account
+      summary: List applications in use
+      description: |-
+        Returns every external application that has at least one connection
+        in the account, grouped with summaries of those connections.
+      responses:
+        '200':
+          description: Applications in use, each with its connection references.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ApplicationsResponse'
+              examples:
+                default:
+                  value:
+                    applications:
+                      - _id: netsuite
+                        refs:
+                          connections:
+                            - _id: 61f92026dd053843b5d72350
+                              createdAt: '2022-01-31T17:05:42.000Z'
+                      - _id: shopify
+                        refs:
+                          connections:
+                            - _id: 62a80ef9ea2474232730eede
+                              createdAt: '2022-06-13T21:44:41.000Z'
+                      - _id: 3mftp_tp
+                        refs:
+                          connections:
+                            - _id: 68efa98330271865e67477de
+                              createdAt: '2025-10-15T14:02:43.371Z'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/shared/ashares:
+    get:
+      x-internal: false
+      operationId: listSharedAccounts
+      tags:
+        - Account
+      summary: List accounts shared with you
+      description: |-
+        Returns every account that other users have shared with the current
+        user. This is the inverse of `GET /v1/ashares`, which lists users
+        who have access to *your* account.
+      responses:
+        '200':
+          description: Array of shared-account entries.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/SharedAccount'
+              examples:
+                default:
+                  value:
+                    - _id: 612345abcdef6789012345ab
+                      accepted: true
+                      accessLevel: administrator
+                      integrationAccessLevel: []
+                      ownerUser:
+                        _id: 5ab979f5038e555b2a95c385
+                        name: Account Owner
+                        email: owner@example.com
+                      lastModified: '2025-11-15T12:00:00.000Z'
+                      createdAt: '2025-11-15T12:00:00.000Z'
+                    - _id: 71a234bcdef5678901234567
+                      accepted: true
+                      accessLevel: monitor
+                      integrationAccessLevel:
+                        - _integrationId: 60f1a2b3c4d5e6f7a8b9c0d1
+                          accessLevel: manage
+                      ownerUser:
+                        _id: 62b456e7890abcdef1234567
+                        name: Partner Admin
+                        email: partner@example.com
+                      lastModified: '2026-02-10T08:30:00.000Z'
+                      createdAt: '2026-01-05T14:00:00.000Z'
+        '204':
+          description: No accounts are shared with the current user.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/shared/sshares:
+    get:
+      x-internal: false
+      operationId: listSharedStacks
+      tags:
+        - Account
+      summary: List stack share invitations
+      description: |-
+        Returns stack-share records for the current user, including share
+        status, the user who shared, and a stack summary. To list usable
+        stacks directly, use `GET /v1/shared/stacks`.
+      responses:
+        '200':
+          description: Array of stack share entries.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/StackShare'
+              examples:
+                default:
+                  value:
+                    - _id: 69f53622861a268851c836d0
+                      accepted: true
+                      ownerUser:
+                        _id: 69790a36cf9d563e23345f49
+                        email: partner@example.com
+                        name: Partner User
+                      stack:
+                        _id: 69f536192e7966f4032f2299
+                        name: sample
+                        type: server
+        '204':
+          description: No stacks are shared with the current user.
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+  /v1/shared/stacks:
+    get:
+      x-internal: false
+      operationId: listSharedStackResources
+      tags:
+        - Account
+      summary: List available stacks
+      description: |-
+        Returns every stack the current account can use — both owned and
+        accepted shared stacks. For share metadata (who shared, acceptance
+        status), use `GET /v1/shared/sshares`.
+      responses:
+        '200':
+          description: Array of stacks (may be empty).
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Stack'
+              examples:
+                oneStack:
+                  summary: One stack available
+                  value:
+                    - _id: 69f536192e7966f4032f2299
+                      name: Production On-Prem Agent
+                      type: server
+                      server:
+                        hostURI: https://agent.example.com:7020
+                        systemToken: '********'
+                        ipRanges:
+                          - 10.0.0.0/8
+                empty:
+                  summary: No stacks available
+                  value: []
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  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
+  schemas:
+    ApplicationUsage:
+      type: object
+      description: An application and its connections in this account.
+      properties:
+        _id:
+          type: string
+          examples:
+            - netsuite
+          description: |-
+            Application identifier — a well-known slug like `netsuite` or `shopify`,
+            a trading-partner code like `3mftp_tp`, or an HTTP-connector ID.
+        refs:
+          type: object
+          description: Resources tied to this application.
+          properties:
+            connections:
+              type: array
+              description: Connection summaries. Fetch `GET /v1/connections/{_id}` for full details.
+              items:
+                type: object
+                properties:
+                  _id:
+                    type: string
+                    format: objectId
+                    x-celigo-refModel: connections
+                    examples:
+                      - 61f92026dd053843b5d72350
+                    description: Connection identifier.
+                  createdAt:
+                    type: string
+                    format: date-time
+                    examples:
+                      - '2022-01-31T17:05:42.000Z'
+                    description: Timestamp when the connection was created.
+    ApplicationsResponse:
+      type: object
+      description: List of external applications that have at least one connection in the account.
+      properties:
+        applications:
+          type: array
+          description: Applications in use, sorted alphabetically by `_id`.
+          items:
+            $ref: '#/components/schemas/ApplicationUsage'
+    SharedAccount:
+      type: object
+      description: |-
+        A share record granting the current user access to another user's account.
+        This is the inverse of `GET /v1/ashares`: here the current user is the
+        recipient, and `ownerUser` is who shared.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          examples:
+            - 612345abcdef6789012345ab
+          description: Unique identifier for this share record, not a user or account ID.
+        accepted:
+          type: boolean
+          description: |-
+            When true, the current user has accepted the invitation.
+            Unaccepted shares appear in the list but cannot be acted on.
+        accessLevel:
+          type: string
+          description: |-
+            Account-wide permission level. Mutually exclusive with
+            `integrationAccessLevel` when set to `administrator` or `manage`.
+            When set to `monitor`, per-integration overrides may elevate
+            specific integrations to `manage`. Absent when the user has
+            only per-integration access.
+          enum:
+            - administrator
+            - manage
+            - monitor
+          x-enumDescriptions:
+            administrator: Full administration including user management and account settings
+            manage: Create and edit integrations and resources, but not account settings or users
+            monitor: Read-only view of integrations, flows, and errors
+        integrationAccessLevel:
+          type: array
+          description: |-
+            Per-integration access grants. Ignored when `accessLevel` is
+            `administrator` or `manage`. When `accessLevel` is `monitor`,
+            elevates specific integrations to `manage`. When `accessLevel`
+            is absent, defines the only integrations the user can access.
+          items:
+            type: object
+            properties:
+              _integrationId:
+                type: string
+                format: objectId
+                x-celigo-refModel: integrations
+                examples:
+                  - 60f1a2b3c4d5e6f7a8b9c0d1
+                description: Integration this override applies to.
+              accessLevel:
+                type: string
+                enum:
+                  - monitor
+                  - manage
+                x-enumDescriptions:
+                  monitor: Read-only view of the integration and its errors
+                  manage: Create and edit the integration and its resources
+                description: Permission level for this integration.
+        ownerUser:
+          type: object
+          description: The user who shared their account.
+          properties:
+            _id:
+              type: string
+              format: objectId
+              x-celigo-refModel: users
+              examples:
+                - 5ab979f5038e555b2a95c385
+              description: User ID of the account owner.
+            name:
+              type: string
+              examples:
+                - Account Owner
+              description: Display name of the account owner.
+            email:
+              type: string
+              format: email
+              examples:
+                - owner@example.com
+              description: Email address of the account owner.
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          examples:
+            - '2025-11-15T12:00:00.000Z'
+          description: Timestamp when this share record was last updated.
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          examples:
+            - '2025-11-15T12:00:00.000Z'
+          description: Timestamp when this share record was created.
+    StackShare:
+      type: object
+      description: |-
+        A share record granting the current user access to another user's stack.
+        The `_id` here is the share record — the stack's own ID is in `stack._id`.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          examples:
+            - 69f53622861a268851c836d0
+          description: Unique identifier for the share record, not the stack itself.
+        accepted:
+          type: boolean
+          description: |-
+            When true, the current user has accepted the invitation.
+            The stack cannot be used until accepted.
+        ownerUser:
+          type: object
+          description: The user who shared the stack.
+          properties:
+            _id:
+              type: string
+              format: objectId
+              x-celigo-refModel: users
+              examples:
+                - 69790a36cf9d563e23345f49
+              description: User ID of the stack owner.
+            name:
+              type: string
+              examples:
+                - Partner User
+              description: Display name of the stack owner.
+            email:
+              type: string
+              format: email
+              examples:
+                - partner@example.com
+              description: Email address of the stack owner.
+        stack:
+          type: object
+          description: Summary of the shared stack.
+          properties:
+            _id:
+              type: string
+              format: objectId
+              x-celigo-refModel: stacks
+              examples:
+                - 69f536192e7966f4032f2299
+              description: Stack identifier. Fetch full configuration with `GET /v1/stacks/{_id}`.
+            name:
+              type: string
+              examples:
+                - Production Lambda Stack
+              description: Display name shown in the UI when selecting a stack.
+            type:
+              type: string
+              enum:
+                - server
+                - lambda
+              x-enumDescriptions:
+                server: On-premise agent installed on your own infrastructure
+                lambda: AWS Lambda function managed in your own AWS account
+              description: Execution environment type.
+    Stack:
+      type: object
+      description: |-
+        Summary of a stack available to the account, returned by
+        `GET /v1/shared/stacks`. For the full stack resource (CRUD,
+        dependencies), use `GET /v1/stacks/{_id}`.
+      properties:
+        _id:
+          type: string
+          format: objectId
+          examples:
+            - 69f536192e7966f4032f2299
+          description: Unique identifier for this stack.
+        name:
+          type: string
+          examples:
+            - Production On-Prem Agent
+          description: Display name shown in the UI when selecting a stack.
+        type:
+          type: string
+          enum:
+            - server
+            - lambda
+          x-enumDescriptions:
+            server: On-premise agent installed on your own infrastructure.
+            lambda: AWS Lambda function managed in your own AWS account.
+          description: Execution environment type that determines which configuration block is present.
+        server:
+          type: object
+          description: Configuration for the on-premise agent process. Present when `type` is `server`.
+          properties:
+            systemToken:
+              type: string
+              description: |-
+                Token the on-premise agent uses to authenticate with the
+                Celigo platform. Masked in GET responses.
+            hostURI:
+              type: string
+              format: uri
+              examples:
+                - https://agent.example.com:7020
+              description: |-
+                Base URL where the on-premise agent is reachable.
+                The platform sends integration traffic to this address.
+            ipRanges:
+              type: array
+              description: |-
+                CIDR ranges allowed to connect to the agent. Requests from
+                IPs outside these ranges are rejected.
+              items:
+                type: string
+                examples:
+                  - 10.0.0.0/8
+        lambda:
+          type: object
+          description: Configuration for the AWS Lambda execution environment. Present when `type` is `lambda`.
+          properties:
+            accessKeyId:
+              type: string
+              description: |-
+                AWS IAM access key ID with permission to invoke the Lambda
+                function. Masked in GET responses.
+            secretAccessKey:
+              type: string
+              description: |-
+                AWS IAM secret access key paired with `accessKeyId`.
+                Masked in GET responses.
+            awsRegion:
+              type: string
+              enum:
+                - us-east-1
+                - us-east-2
+                - us-west-1
+                - us-west-2
+                - ap-northeast-2
+                - ap-southeast-1
+                - ap-southeast-2
+                - ap-northeast-1
+                - ap-south-1
+                - eu-central-1
+                - eu-west-1
+              x-enumDescriptions:
+                us-east-1: US East (N. Virginia)
+                us-east-2: US East (Ohio)
+                us-west-1: US West (N. California)
+                us-west-2: US West (Oregon)
+                ap-northeast-2: Asia Pacific (Seoul)
+                ap-southeast-1: Asia Pacific (Singapore)
+                ap-southeast-2: Asia Pacific (Sydney)
+                ap-northeast-1: Asia Pacific (Tokyo)
+                ap-south-1: Asia Pacific (Mumbai)
+                eu-central-1: Europe (Frankfurt)
+                eu-west-1: Europe (Ireland)
+              description: |-
+                AWS region where the Lambda function is deployed.
+                Must match the region used when creating the function.
+            functionName:
+              type: string
+              examples:
+                - celigo-extension-handler
+              description: |-
+                Exact name of the Lambda function to invoke.
+                Must match the function name in your AWS account.
+            language:
+              type: string
+              enum:
+                - Node.js
+                - C#
+                - Java
+                - Other
+              x-enumDescriptions:
+                Node.js: Node.js runtime
+                C#: .NET (C#) runtime
+                Java: Java runtime
+                Other: Custom or unlisted runtime
+              description: |-
+                Runtime language the Lambda function is written in.
+                Controls how the platform serializes payloads sent to the function.
+      if:
+        properties:
+          type:
+            const: server
+      then:
+        required:
+          - server
+      else:
+        required:
+          - lambda
+x-enable-proxy: true
+x-internal: false