@celigo/api-specs 0.2.1

package/dist/enduser.yml

@@ -0,0 +1,1724 @@
+openapi: 3.2.0
+info:
+  version: 1.0.0
+  title: End Users
+  description: API for managing end users — MCP-only consumers of an account — and the groups and roles that control their access.
+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: End Users
+    description: |-
+      End users are people who consume an account's MCP servers without
+      getting workspace access — they sign in through MCP OAuth, optionally
+      via an external IdP. Use these endpoints to invite end users (singly or
+      in bulk), list and revoke them, and inspect the effective MCP tool
+      access compiled from their grants, groups, and roles.
+
+      ## End user schema
+
+      {% openapi-schemas spec="enduser" schemas="EndUser" grouped="true" %}
+  - name: Groups
+    description: |-
+      Groups bundle roles and resource grants so end-user access can be
+      managed collectively. End users receive a group's access through
+      membership, added manually or synced from an identity provider's group
+      claims.
+
+      ## Group schema
+
+      {% openapi-schemas spec="enduser" schemas="Group" grouped="true" %}
+  - name: Roles
+    description: |-
+      Roles are named, reusable bundles of resource grants. Assign them to
+      end users directly or pin them to groups; their grants are compiled
+      into each member's effective access.
+
+      ## Role schema
+
+      {% openapi-schemas spec="enduser" schemas="Role" grouped="true" %}
+paths:
+  /v1/endusers:
+    get:
+      x-internal: false
+      summary: List end users
+      operationId: listEndUsers
+      tags:
+        - End Users
+      description: |-
+        Returns the account's end users with identity fields (`email`, `name`,
+        `lastSignIn`) joined from each user record, plus a computed
+        `hasWorkspaceShare` flag indicating whether the same person also holds a
+        workspace access record. Requires account owner or administrator access.
+      parameters:
+        - name: provisionedBy
+          in: query
+          required: false
+          description: Return only end users created by the given provisioning source.
+          schema:
+            type: string
+            enum:
+              - invite
+              - jit
+            x-enumDescriptions:
+              invite: Created through an explicit invite (or by migration from a workspace user)
+              jit: Provisioned just-in-time on first sign-in through an external IdP
+      responses:
+        '200':
+          description: List of end users.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/EndUser'
+              examples:
+                default:
+                  value:
+                    - _id: 68b1c2d3e4f5a6b7c8d9e0f1
+                      _userId: 5f8d43a1b9e5a80011a35f2c
+                      _sharedWithUserId: 624774a6a7574d3ed9f9a5cc
+                      userType: end-user
+                      provisionedBy: invite
+                      accepted: true
+                      dismissed: false
+                      disabled: false
+                      groupMemberships:
+                        - _groupId: 68a1b2c3d4e5f6a7b8c9d0e1
+                          source: manual
+                      resourceGrants:
+                        - resourceType: mcpServer
+                          _resourceId: 6a1b2c3d4e5f6a7b8c9d0e1f
+                          capabilities:
+                            - tool:all
+                      _roleIds: []
+                      email: enduser@example.com
+                      name: Ana Enduser
+                      lastSignIn: '2026-08-02T17:02:59.370Z'
+                      hasWorkspaceShare: false
+                      createdAt: '2026-07-01T09:15:32Z'
+                      lastModified: '2026-08-15T14:30:15Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+  /v1/endusers/invite:
+    post:
+      x-internal: false
+      summary: Invite an end user
+      operationId: inviteEndUser
+      tags:
+        - End Users
+      description: |-
+        Finds or creates the user by email, creates an end-user access record,
+        applies the requested group memberships and direct grants, and sends an
+        invite email. Account owners cannot be invited as end users. Requires
+        account owner or administrator access.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/InviteRequest'
+            examples:
+              minimal:
+                summary: Invite by email only
+                value:
+                  email: enduser@example.com
+              withAccess:
+                summary: Invite with groups and a direct grant
+                value:
+                  email: enduser@example.com
+                  name: Ana Enduser
+                  groupIds:
+                    - 68a1b2c3d4e5f6a7b8c9d0e1
+                  directGrants:
+                    - resourceType: mcpServer
+                      _resourceId: 6a1b2c3d4e5f6a7b8c9d0e1f
+                      capabilities:
+                        - tool:all
+      responses:
+        '201':
+          description: End user invited.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/InviteResponse'
+              examples:
+                default:
+                  value:
+                    _userId: 5f8d43a1b9e5a80011a35f2c
+                    _ashareId: 68b1c2d3e4f5a6b7c8d9e0f1
+                    status: invited
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '409':
+          description: |-
+            An end-user record already exists for this user in the account.
+            Error code: `enduser_ashare_exists`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/endusers/invite/bulk:
+    post:
+      x-internal: false
+      summary: Invite end users in bulk
+      operationId: inviteEndUsersBulk
+      tags:
+        - End Users
+      description: |-
+        Invites 1–100 end users in one request, applying the same optional
+        `groupIds` and `directGrants` to every invite. Processing is sequential
+        and partial-success: a failed item never aborts the batch, so the
+        response is HTTP 200 with a per-email result even when some items fail.
+        Only top-level structural errors (missing or non-array `emails`, more
+        than 100 emails, non-array `groupIds`/`directGrants`) return 400.
+        Requires account owner or administrator access.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/BulkInviteRequest'
+            examples:
+              default:
+                value:
+                  emails:
+                    - a@example.com
+                    - b@example.com
+                  groupIds:
+                    - 68a1b2c3d4e5f6a7b8c9d0e1
+      responses:
+        '200':
+          description: Batch processed, including partial success. One result per input email.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/BulkInviteResponse'
+              examples:
+                partialSuccess:
+                  value:
+                    summary:
+                      total: 2
+                      invited: 1
+                      failed: 1
+                      skipped: 0
+                    results:
+                      - email: a@example.com
+                        status: invited
+                        _userId: 5f8d43a1b9e5a80011a35f2c
+                        _ashareId: 68b1c2d3e4f5a6b7c8d9e0f1
+                      - email: b@example.com
+                        status: failed
+                        code: enduser_ashare_exists
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+  /v1/endusers/{_ashareId}:
+    delete:
+      x-internal: false
+      summary: Revoke an end user
+      operationId: revokeEndUser
+      tags:
+        - End Users
+      description: |-
+        Soft-deletes the end-user access record and clears its group
+        memberships. Any workspace access record the same person holds is
+        unaffected. Requires account owner or administrator access.
+      parameters:
+        - name: _ashareId
+          in: path
+          required: true
+          description: End-user access-record id (from the end users list).
+          schema:
+            type: string
+            format: objectId
+      responses:
+        '204':
+          description: End user revoked.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/endusers/{_ashareId}/effective-access:
+    get:
+      x-internal: false
+      summary: Get an end user's effective access
+      operationId: getEndUserEffectiveAccess
+      tags:
+        - End Users
+      description: |-
+        Compiles the end user's effective MCP server tool access with source
+        attribution — the union of direct grants, group grants, role grants, and
+        permission sets. The result is recomputed on every request rather than
+        cached. Requires account owner or administrator access.
+      parameters:
+        - name: _ashareId
+          in: path
+          required: true
+          description: End-user access-record id (from the end users list).
+          schema:
+            type: string
+            format: objectId
+      responses:
+        '200':
+          description: Compiled effective access with attribution.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/EffectiveAccess'
+              examples:
+                default:
+                  value:
+                    _ashareId: 68b1c2d3e4f5a6b7c8d9e0f1
+                    _userId: 624774a6a7574d3ed9f9a5cc
+                    userType: end-user
+                    provisionedBy: invite
+                    groups:
+                      - _id: 68a1b2c3d4e5f6a7b8c9d0e1
+                        name: Finance
+                        source: manual
+                    roles:
+                      - _id: 68c1d2e3f4a5b6c7d8e9f0a1
+                        name: Finance tools
+                        via:
+                          - group:Finance
+                    access:
+                      - resourceType: mcpServer
+                        _resourceId: 6a1b2c3d4e5f6a7b8c9d0e1f
+                        resourceName: Finance MCP
+                        tools:
+                          - _id: 6b2c3d4e5f6a7b8c9d0e1f2a
+                            name: lookup-invoice
+                            via:
+                              - role:Finance tools (group:Finance)
+                        deniedTools: []
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/groups:
+    get:
+      x-internal: false
+      summary: List groups
+      operationId: listGroups
+      tags:
+        - Groups
+      description: |-
+        Returns all active groups in the account. Requires account owner or
+        administrator access.
+      responses:
+        '200':
+          description: List of groups.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Group'
+              examples:
+                default:
+                  value:
+                    - _id: 68a1b2c3d4e5f6a7b8c9d0e1
+                      _userId: 5f8d43a1b9e5a80011a35f2c
+                      name: Finance
+                      description: Finance department end users
+                      intendedFor:
+                        - end-user
+                      _roleIds:
+                        - 68c1d2e3f4a5b6c7d8e9f0a1
+                      resourceGrants: []
+                      hasIdpSyncedMembers: false
+                      createdAt: '2026-07-01T09:15:32Z'
+                      lastModified: '2026-08-15T14:30:15Z'
+        '204':
+          description: No groups exist in the account.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+    post:
+      x-internal: false
+      summary: Create a group
+      operationId: createGroup
+      tags:
+        - Groups
+      description: |-
+        Creates a group for end-user access management. Group names must be
+        unique within the account (case-insensitive), and any `_roleIds` or
+        `resourceGrants._resourceId` values must reference resources owned by
+        the same account. Requires account owner or administrator access.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/GroupRequest'
+            examples:
+              minimal:
+                summary: Name only
+                value:
+                  name: Finance
+              withAccess:
+                summary: With a pinned role and a direct grant
+                value:
+                  name: Finance
+                  description: Finance department end users
+                  intendedFor:
+                    - end-user
+                  _roleIds:
+                    - 68c1d2e3f4a5b6c7d8e9f0a1
+                  resourceGrants:
+                    - resourceType: mcpServer
+                      _resourceId: 6a1b2c3d4e5f6a7b8c9d0e1f
+                      capabilities:
+                        - tool:all
+      responses:
+        '201':
+          description: Group created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Group'
+              examples:
+                default:
+                  value:
+                    _id: 68a1b2c3d4e5f6a7b8c9d0e1
+                    _userId: 5f8d43a1b9e5a80011a35f2c
+                    name: Finance
+                    description: Finance department end users
+                    intendedFor:
+                      - end-user
+                    _roleIds:
+                      - 68c1d2e3f4a5b6c7d8e9f0a1
+                    resourceGrants: []
+                    hasIdpSyncedMembers: false
+                    createdAt: '2026-07-01T09:15:32Z'
+                    lastModified: '2026-07-01T09:15:32Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '409':
+          description: A group with this name already exists in the account.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/groups/{_id}:
+    get:
+      x-internal: false
+      summary: Get a group
+      operationId: getGroup
+      tags:
+        - Groups
+      description: Retrieves a single group by ID.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Group ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: groups
+      responses:
+        '200':
+          description: Group details.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Group'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Update a group
+      operationId: updateGroup
+      tags:
+        - Groups
+      description: |-
+        Replaces the group's writable fields. Prefer resending the complete
+        object — omitted fields are not preserved. Requires account owner or
+        administrator access.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Group ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: groups
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/GroupRequest'
+            examples:
+              rename:
+                summary: Rename the group
+                value:
+                  name: Finance EMEA
+      responses:
+        '200':
+          description: Updated group.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Group'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '409':
+          description: A group with this name already exists in the account.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    delete:
+      x-internal: false
+      summary: Delete a group
+      operationId: deleteGroup
+      tags:
+        - Groups
+      description: |-
+        Soft-deletes the group and removes the corresponding membership entry
+        from every end user in the account. Requires account owner or
+        administrator access.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Group ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: groups
+      responses:
+        '204':
+          description: Group deleted.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/groups/{_groupId}/members:
+    post:
+      x-internal: false
+      summary: Add end users to a group
+      operationId: addGroupMembers
+      tags:
+        - Groups
+      description: |-
+        Bulk-adds up to 100 end users to the group as manual memberships. The
+        operation is idempotent for end users already in the group. Requires
+        account owner or administrator access.
+      parameters:
+        - name: _groupId
+          in: path
+          required: true
+          description: Group ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: groups
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/GroupMembersRequest'
+            examples:
+              default:
+                value:
+                  _ashareIds:
+                    - 68b1c2d3e4f5a6b7c8d9e0f1
+      responses:
+        '200':
+          description: Members added.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GroupMembersResponse'
+              examples:
+                default:
+                  value:
+                    updated: 1
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+  /v1/groups/{_groupId}/members/remove:
+    post:
+      x-internal: false
+      summary: Remove end users from a group
+      operationId: removeGroupMembers
+      tags:
+        - Groups
+      description: |-
+        Bulk-removes manual memberships from the group. Only manual memberships
+        can be removed this way — attempting to remove an IdP-synced membership
+        returns 409; change the IdP group mapping instead. Uses POST rather than
+        DELETE so the request body survives proxies and CDNs. Requires account
+        owner or administrator access.
+      parameters:
+        - name: _groupId
+          in: path
+          required: true
+          description: Group ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: groups
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/GroupMembersRequest'
+            examples:
+              default:
+                value:
+                  _ashareIds:
+                    - 68b1c2d3e4f5a6b7c8d9e0f1
+      responses:
+        '200':
+          description: Members removed.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/GroupMembersResponse'
+              examples:
+                default:
+                  value:
+                    updated: 1
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '409':
+          description: |-
+            One or more of the memberships is IdP-synced and cannot be removed
+            manually. Error code: `conflict`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+  /v1/roles:
+    get:
+      x-internal: false
+      summary: List roles
+      operationId: listRoles
+      tags:
+        - Roles
+      description: |-
+        Returns all active roles in the account. Requires account owner or
+        administrator access.
+      responses:
+        '200':
+          description: List of roles.
+          content:
+            application/json:
+              schema:
+                type: array
+                items:
+                  $ref: '#/components/schemas/Role'
+              examples:
+                default:
+                  value:
+                    - _id: 68c1d2e3f4a5b6c7d8e9f0a1
+                      _userId: 5f8d43a1b9e5a80011a35f2c
+                      name: Finance tools
+                      description: Read access to finance MCP tools
+                      resourceGrants:
+                        - resourceType: mcpServer
+                          _resourceId: 6a1b2c3d4e5f6a7b8c9d0e1f
+                          capabilities:
+                            - pset:6c3d4e5f6a7b8c9d0e1f2a3b
+                      createdAt: '2026-07-01T09:15:32Z'
+                      lastModified: '2026-08-15T14:30:15Z'
+        '204':
+          description: No roles exist in the account.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+    post:
+      x-internal: false
+      summary: Create a role
+      operationId: createRole
+      tags:
+        - Roles
+      description: |-
+        Creates a role. Role names must be unique within the account
+        (case-insensitive), and `resourceGrants._resourceId` values must
+        reference resources owned by the same account. Requires account owner or
+        administrator access.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RoleRequest'
+            examples:
+              default:
+                value:
+                  name: Finance tools
+                  description: Read access to finance MCP tools
+                  resourceGrants:
+                    - resourceType: mcpServer
+                      _resourceId: 6a1b2c3d4e5f6a7b8c9d0e1f
+                      capabilities:
+                        - pset:6c3d4e5f6a7b8c9d0e1f2a3b
+      responses:
+        '201':
+          description: Role created.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Role'
+              examples:
+                default:
+                  value:
+                    _id: 68c1d2e3f4a5b6c7d8e9f0a1
+                    _userId: 5f8d43a1b9e5a80011a35f2c
+                    name: Finance tools
+                    description: Read access to finance MCP tools
+                    resourceGrants:
+                      - resourceType: mcpServer
+                        _resourceId: 6a1b2c3d4e5f6a7b8c9d0e1f
+                        capabilities:
+                          - pset:6c3d4e5f6a7b8c9d0e1f2a3b
+                    createdAt: '2026-07-01T09:15:32Z'
+                    lastModified: '2026-07-01T09:15:32Z'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '409':
+          description: A role with this name already exists in the account.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+  /v1/roles/{_id}:
+    get:
+      x-internal: false
+      summary: Get a role
+      operationId: getRole
+      tags:
+        - Roles
+      description: Retrieves a single role by ID.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Role ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: roles
+      responses:
+        '200':
+          description: Role details.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Role'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+    put:
+      x-internal: false
+      summary: Update a role
+      operationId: updateRole
+      tags:
+        - Roles
+      description: |-
+        Replaces the role's writable fields. Prefer resending the complete
+        object — omitted fields are not preserved. Requires account owner or
+        administrator access.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Role ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: roles
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/RoleRequest'
+            examples:
+              updateDescription:
+                summary: Update the description
+                value:
+                  name: Finance tools
+                  description: Updated description
+      responses:
+        '200':
+          description: Updated role.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Role'
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+        '409':
+          description: A role with this name already exists in the account.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '422':
+          $ref: '#/components/responses/422-unprocessable-entity'
+    delete:
+      x-internal: false
+      summary: Delete a role
+      operationId: deleteRole
+      tags:
+        - Roles
+      description: |-
+        Soft-deletes the role and removes it from the `_roleIds` of every group
+        in the account. Requires account owner or administrator access.
+      parameters:
+        - name: _id
+          in: path
+          required: true
+          description: Role ID.
+          schema:
+            type: string
+            format: objectId
+            x-celigo-refModel: roles
+      responses:
+        '204':
+          description: Role deleted.
+        '400':
+          $ref: '#/components/responses/400-bad-request'
+        '401':
+          $ref: '#/components/responses/401-unauthorized'
+        '403':
+          $ref: '#/components/responses/403-forbidden'
+        '404':
+          $ref: '#/components/responses/404-not-found'
+components:
+  securitySchemes:
+    bearerAuth:
+      type: http
+      scheme: bearer
+  schemas:
+    GroupMembership:
+      type: object
+      description: An end user's membership in a group, with the source that created it.
+      properties:
+        _groupId:
+          type: string
+          format: objectId
+          x-celigo-refModel: groups
+          examples:
+            - 68a1b2c3d4e5f6a7b8c9d0e1
+          description: Group the end user belongs to.
+        source:
+          type: string
+          enum:
+            - manual
+            - idp
+          x-enumDescriptions:
+            manual: Membership was added by an owner or administrator (invite or group members API)
+            idp: Membership is synced from the identity provider's group claims
+          description: |-
+            How the membership was created. IdP-synced memberships cannot be
+            removed through the group members API — change the IdP group mapping
+            instead.
+    ResourceGrant:
+      type: object
+      description: |-
+        Grants access to a resource (currently MCP servers only). A grant names
+        the resource, or applies as a wildcard across all resources of the type,
+        and lists the capabilities granted on it.
+      required:
+        - resourceType
+        - capabilities
+      properties:
+        resourceType:
+          type: string
+          enum:
+            - mcpServer
+          x-enumDescriptions:
+            mcpServer: Grants access to an MCP server and its tools, APIs, or permission sets.
+          description: Resource type this grant applies to.
+        _resourceId:
+          type:
+            - string
+            - 'null'
+          format: objectId
+          x-celigo-refModel: mcpservers
+          examples:
+            - 6a1b2c3d4e5f6a7b8c9d0e1f
+          description: |-
+            MCP server this grant applies to. Omit or set to null for a wildcard
+            grant across all MCP servers in the account.
+        capabilities:
+          type: array
+          minItems: 1
+          description: Capabilities granted on the target resource.
+          items:
+            type: string
+            description: |-
+              Capability string. For `mcpServer` grants: `tool:all`,
+              `tool:<24-char-hex-id>` (an IO tool `_toolId` or attached prompt `_id`),
+              `api:all`, `api:<24-char-hex-apiId>`, or
+              `pset:<24-char-hex-permissionSetId>` referencing a permission set
+              defined on the target MCP server.
+            examples:
+              - tool:all
+    EndUser:
+      type: object
+      description: |-
+        An end user's access record in the account. End users authenticate through
+        MCP OAuth (optionally via an external IdP) to use MCP servers; they do not
+        get workspace access. The `_id` is the access-record id, not the user's own
+        id — the user's identity is in `_sharedWithUserId`.
+      required:
+        - _id
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          examples:
+            - 68b1c2d3e4f5a6b7c8d9e0f1
+          description: Access-record id for this end user in the account.
+        _userId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: users
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+          description: Account owner's user id.
+        _sharedWithUserId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: users
+          examples:
+            - 624774a6a7574d3ed9f9a5cc
+          description: The end user's own user id.
+        userType:
+          type: string
+          enum:
+            - end-user
+          x-enumDescriptions:
+            end-user: MCP-only access record, separate from workspace user access
+          description: Distinguishes end-user access records from workspace access records.
+        provisionedBy:
+          type: string
+          enum:
+            - invite
+            - jit
+          x-enumDescriptions:
+            invite: Created through an explicit invite (or by migration from a workspace user)
+            jit: Provisioned just-in-time on first sign-in through an external IdP
+          description: How this end-user record was created.
+        accepted:
+          type: boolean
+          description: When true, the end user has completed invite setup (or was JIT-provisioned).
+        dismissed:
+          type: boolean
+          description: When true, the end user has declined the invitation.
+        disabled:
+          type: boolean
+          description: When true, the end user's access is suspended without deleting the record.
+        groupMemberships:
+          type: array
+          description: Groups this end user belongs to, with the source of each membership.
+          items:
+            $ref: '#/components/schemas/GroupMembership'
+        resourceGrants:
+          type: array
+          description: Direct resource grants on this end user, in addition to any group- or role-derived access.
+          items:
+            $ref: '#/components/schemas/ResourceGrant'
+        _roleIds:
+          type: array
+          description: Roles assigned directly to this end user.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: roles
+        email:
+          type: string
+          format: email
+          readOnly: true
+          examples:
+            - enduser@example.com
+          description: Email address of the end user, joined from the user record.
+        name:
+          type: string
+          readOnly: true
+          examples:
+            - Ana Enduser
+          description: Display name of the end user, joined from the user record.
+        lastSignIn:
+          type:
+            - string
+            - 'null'
+          format: date-time
+          readOnly: true
+          examples:
+            - '2026-08-02T17:02:59.370Z'
+          description: When the end user last signed in. Null when they have never signed in.
+        hasWorkspaceShare:
+          type: boolean
+          readOnly: true
+          description: When true, the same person also has an active workspace access record on this account.
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          examples:
+            - '2026-07-01T09:15:32Z'
+          description: Timestamp when the end-user record was created.
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          examples:
+            - '2026-08-15T14:30:15Z'
+          description: Timestamp when the end-user record was last updated.
+    Error:
+      type: object
+      description: Standard error response envelope returned by integrator.io APIs.
+      properties:
+        errors:
+          type: array
+          description: List of errors that occurred while processing the request.
+          items:
+            type: object
+            properties:
+              code:
+                oneOf:
+                  - type: string
+                  - type: integer
+                description: |-
+                  Machine-readable error code. Usually a string like
+                  `invalid_ref`, `missing_required_field`, or `unauthorized`;
+                  may be an **integer** when the error mirrors an upstream HTTP
+                  status (e.g. `500`) — most commonly returned by connection-ping
+                  and adaptor-proxy responses.
+              message:
+                type: string
+                description: Human-readable description of the error.
+              field:
+                type: string
+                description: |-
+                  Optional pointer to the document field that caused the error.
+                  Used by structural validation errors (`missing_required_field`,
+                  `invalid_ref`) to indicate which field is at fault
+                  (e.g. `_id`, `type`, `http.baseURI`).
+              source:
+                type: string
+                description: |-
+                  Optional origin layer for the error — e.g. `application` when
+                  the error came from the remote system the adaptor called,
+                  `connector` when the adaptor itself rejected the request.
+            required:
+              - message
+      required:
+        - errors
+    InviteRequest:
+      type: object
+      description: Invitation details for a single end user.
+      required:
+        - email
+      properties:
+        email:
+          type: string
+          format: email
+          examples:
+            - enduser@example.com
+          description: Email address to invite. Normalized to lowercase and trimmed.
+        name:
+          type: string
+          examples:
+            - Ana Enduser
+          description: Display name for the invited user. Defaults to the email local-part when omitted.
+        groupIds:
+          type: array
+          description: Groups to add the end user to as manual memberships.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: groups
+        directGrants:
+          type: array
+          description: Direct resource grants placed on the new end-user record.
+          items:
+            $ref: '#/components/schemas/ResourceGrant'
+        resourceGrants:
+          type: array
+          description: Alias for `directGrants`; send one or the other.
+          items:
+            $ref: '#/components/schemas/ResourceGrant'
+    InviteResponse:
+      type: object
+      description: Result of a successful single invite.
+      properties:
+        _userId:
+          type: string
+          format: objectId
+          x-celigo-refModel: users
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+          description: Account owner's user id.
+        _ashareId:
+          type: string
+          format: objectId
+          examples:
+            - 68b1c2d3e4f5a6b7c8d9e0f1
+          description: Access-record id of the newly created end user.
+        status:
+          type: string
+          enum:
+            - invited
+          x-enumDescriptions:
+            invited: The end user was created and the invite email was sent
+          description: Outcome of the invite.
+    BulkInviteRequest:
+      type: object
+      description: |-
+        Batch invitation for up to 100 end users. The optional `groupIds` and
+        `directGrants` are shared and applied identically to every invite in
+        the batch.
+      required:
+        - emails
+      properties:
+        emails:
+          type: array
+          minItems: 1
+          maxItems: 100
+          description: Email addresses to invite. Normalized to lowercase, trimmed, and de-duplicated within the batch.
+          items:
+            type: string
+            format: email
+        groupIds:
+          type: array
+          description: Groups added as manual memberships on every created end-user record.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: groups
+        directGrants:
+          type: array
+          description: Direct resource grants applied identically to every invite.
+          items:
+            $ref: '#/components/schemas/ResourceGrant'
+        resourceGrants:
+          type: array
+          description: Alias for `directGrants`; send one or the other.
+          items:
+            $ref: '#/components/schemas/ResourceGrant'
+    BulkInviteResponse:
+      type: object
+      description: |-
+        Batch outcome with one result per input email, in input order. Processing
+        is partial-success — a failed item never aborts the batch.
+      required:
+        - summary
+        - results
+      properties:
+        summary:
+          type: object
+          description: Aggregate counts for the batch.
+          required:
+            - total
+            - invited
+            - failed
+            - skipped
+          properties:
+            total:
+              type: integer
+              description: Number of input emails. Equals invited + failed + skipped.
+            invited:
+              type: integer
+              description: Number of end users successfully invited.
+            failed:
+              type: integer
+              description: Number of per-email failures. Excludes items skipped as in-batch duplicates.
+            skipped:
+              type: integer
+              description: Number of emails skipped as duplicates within the batch.
+        results:
+          type: array
+          description: One entry per input email, in input order.
+          items:
+            type: object
+            required:
+              - email
+              - status
+            properties:
+              email:
+                type: string
+                description: The normalized email this result corresponds to.
+              status:
+                type: string
+                enum:
+                  - invited
+                  - failed
+                  - skipped_duplicate_in_batch
+                x-enumDescriptions:
+                  invited: The end user was created and the invite email was sent
+                  failed: The invite failed; see `code` for the reason
+                  skipped_duplicate_in_batch: The email appeared earlier in the same batch
+                description: Outcome for this email.
+              _userId:
+                type: string
+                format: objectId
+                x-celigo-refModel: users
+                description: Account owner's user id. Present when status is `invited`.
+              _ashareId:
+                type: string
+                format: objectId
+                description: Access-record id of the created end user. Present when status is `invited`.
+              code:
+                type: string
+                enum:
+                  - email_invalid
+                  - enduser_ashare_exists
+                  - owner_self_invite_not_allowed
+                  - validation_failed
+                  - invite_failed
+                x-enumDescriptions:
+                  email_invalid: The email address is not valid
+                  enduser_ashare_exists: An end-user record already exists for this user in the account
+                  owner_self_invite_not_allowed: Account owners cannot be invited as end users
+                  validation_failed: The shared groupIds or grants failed validation for this item
+                  invite_failed: An unexpected per-item error, caught so the batch can continue
+                description: Failure reason. Present when status is `failed`.
+    EffectiveAccess:
+      type: object
+      description: |-
+        The compiled MCP access for one end user, with source attribution. Access
+        is the union of the end user's direct grants, group grants, role grants
+        (direct or via groups), and permission sets on the target servers,
+        recompiled on every request.
+      properties:
+        _ashareId:
+          type: string
+          format: objectId
+          readOnly: true
+          examples:
+            - 68b1c2d3e4f5a6b7c8d9e0f1
+          description: End-user access-record id this compilation applies to.
+        _userId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: users
+          examples:
+            - 624774a6a7574d3ed9f9a5cc
+          description: The end user's own user id.
+        userType:
+          type: string
+          enum:
+            - end-user
+          x-enumDescriptions:
+            end-user: MCP-only access record, separate from workspace user access
+          description: Type of the access record the compilation was run for.
+        provisionedBy:
+          type: string
+          enum:
+            - invite
+            - jit
+          x-enumDescriptions:
+            invite: Created through an explicit invite (or by migration from a workspace user)
+            jit: Provisioned just-in-time on first sign-in through an external IdP
+          description: How the end-user record was created.
+        groups:
+          type: array
+          description: Groups that contributed to the compiled access.
+          items:
+            type: object
+            properties:
+              _id:
+                type: string
+                format: objectId
+                x-celigo-refModel: groups
+                description: Group id.
+              name:
+                type: string
+                description: Group name.
+              source:
+                type: string
+                enum:
+                  - manual
+                  - idp
+                x-enumDescriptions:
+                  manual: Membership was added by an owner or administrator
+                  idp: Membership is synced from the identity provider's group claims
+                description: How the end user's membership in this group was created.
+        roles:
+          type: array
+          description: Roles that contributed to the compiled access.
+          items:
+            type: object
+            properties:
+              _id:
+                type: string
+                format: objectId
+                x-celigo-refModel: roles
+                description: Role id.
+              name:
+                type: string
+                description: Role name.
+              via:
+                type: array
+                description: Attribution paths through which the role applies, such as `role-direct` or `group:<name>`.
+                items:
+                  type: string
+        access:
+          type: array
+          description: Per-server compiled access, listing the tools the end user can and cannot use.
+          items:
+            type: object
+            properties:
+              resourceType:
+                type: string
+                enum:
+                  - mcpServer
+                x-enumDescriptions:
+                  mcpServer: Access to an MCP server and its tools
+                description: Resource type of the compiled entry.
+              _resourceId:
+                type: string
+                format: objectId
+                x-celigo-refModel: mcpservers
+                description: MCP server this entry applies to.
+              resourceName:
+                type:
+                  - string
+                  - 'null'
+                description: Display name of the MCP server. Null when the server no longer resolves.
+              tools:
+                type: array
+                description: Tools the end user can invoke on this server.
+                items:
+                  type: object
+                  properties:
+                    _id:
+                      type: string
+                      format: objectId
+                      description: Tool id.
+                    name:
+                      type: string
+                      description: Tool name.
+                    via:
+                      type: array
+                      description: |-
+                        Source attribution strings such as `direct`, `group:<name>`,
+                        `pset:<name> (group:<name>)`, `role-direct:<name>`, or
+                        `role:<name> (group:<name>)`.
+                      items:
+                        type: string
+              deniedTools:
+                type: array
+                description: Tools on this server the end user cannot invoke, with the reason.
+                items:
+                  type: object
+                  properties:
+                    _id:
+                      type: string
+                      format: objectId
+                      description: Tool id.
+                    name:
+                      type: string
+                      description: Tool name.
+                    reason:
+                      type: string
+                      description: Why the tool is not available to this end user.
+    Group:
+      type: object
+      description: |-
+        A named bundle of roles and resource grants for end-user access
+        management. End users receive the group's access through membership,
+        whether added manually or synced from an identity provider.
+      required:
+        - _id
+        - name
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          examples:
+            - 68a1b2c3d4e5f6a7b8c9d0e1
+          description: Unique identifier for the group.
+        _userId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: users
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+          description: Account owner's user id.
+        name:
+          type: string
+          examples:
+            - Finance
+          description: Group name, unique within the account (case-insensitive).
+        description:
+          type: string
+          examples:
+            - Finance department end users
+          description: Free-text description of the group's purpose.
+        intendedFor:
+          type: array
+          default:
+            - end-user
+          description: Audience this group is intended for. Defaults to `["end-user"]` when omitted on write.
+          items:
+            type: string
+            enum:
+              - end-user
+            x-enumDescriptions:
+              end-user: The group manages access for end users (MCP consumers)
+        _roleIds:
+          type: array
+          description: Roles pinned to this group. Members receive the roles' grants through the group.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: roles
+        resourceGrants:
+          type: array
+          description: Resource grants attached directly to the group, in addition to any role-derived grants.
+          items:
+            $ref: '#/components/schemas/ResourceGrant'
+        hasIdpSyncedMembers:
+          type: boolean
+          readOnly: true
+          description: |-
+            When true, at least one end user's membership in this group is synced
+            from an identity provider's group claims. Maintained by the server —
+            IdP-synced memberships cannot be removed through the group members
+            API.
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          examples:
+            - '2026-07-01T09:15:32Z'
+          description: Timestamp when the group was created.
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          examples:
+            - '2026-08-15T14:30:15Z'
+          description: Timestamp when the group was last updated.
+    GroupRequest:
+      type: object
+      description: Writable fields for creating or replacing a group.
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          examples:
+            - Finance
+          description: Group name, unique within the account (case-insensitive).
+        description:
+          type: string
+          examples:
+            - Finance department end users
+          description: Free-text description of the group's purpose.
+        intendedFor:
+          type: array
+          default:
+            - end-user
+          description: Audience this group is intended for. Defaults to `["end-user"]` when omitted.
+          items:
+            type: string
+            enum:
+              - end-user
+            x-enumDescriptions:
+              end-user: The group manages access for end users (MCP consumers)
+        _roleIds:
+          type: array
+          description: Roles to pin to this group. Must reference roles owned by the same account.
+          items:
+            type: string
+            format: objectId
+            x-celigo-refModel: roles
+        resourceGrants:
+          type: array
+          description: Resource grants to attach directly to the group. `_resourceId` values must reference resources owned by the same account.
+          items:
+            $ref: '#/components/schemas/ResourceGrant'
+    GroupMembersRequest:
+      type: object
+      description: End users to add to or remove from the group.
+      required:
+        - _ashareIds
+      properties:
+        _ashareIds:
+          type: array
+          minItems: 1
+          maxItems: 100
+          description: End-user access-record ids to add or remove.
+          items:
+            type: string
+            format: objectId
+    GroupMembersResponse:
+      type: object
+      description: Outcome of a bulk membership change.
+      properties:
+        updated:
+          type: integer
+          description: Number of end-user records updated. Members already in (or absent from) the group are not counted.
+    Role:
+      type: object
+      description: |-
+        A named, reusable bundle of resource grants. Roles are assigned to end
+        users directly (`_roleIds` on the end-user record) or pinned to groups,
+        and their grants are compiled into each member's effective access.
+      required:
+        - _id
+        - name
+      properties:
+        _id:
+          type: string
+          format: objectId
+          readOnly: true
+          examples:
+            - 68c1d2e3f4a5b6c7d8e9f0a1
+          description: Unique identifier for the role.
+        _userId:
+          type: string
+          format: objectId
+          readOnly: true
+          x-celigo-refModel: users
+          examples:
+            - 5f8d43a1b9e5a80011a35f2c
+          description: Account owner's user id.
+        name:
+          type: string
+          examples:
+            - Finance tools
+          description: Role name, unique within the account (case-insensitive).
+        description:
+          type: string
+          examples:
+            - Read access to finance MCP tools
+          description: Free-text description of the role's purpose.
+        resourceGrants:
+          type: array
+          description: Resource grants this role carries.
+          items:
+            $ref: '#/components/schemas/ResourceGrant'
+        createdAt:
+          type: string
+          format: date-time
+          readOnly: true
+          examples:
+            - '2026-07-01T09:15:32Z'
+          description: Timestamp when the role was created.
+        lastModified:
+          type: string
+          format: date-time
+          readOnly: true
+          examples:
+            - '2026-08-15T14:30:15Z'
+          description: Timestamp when the role was last updated.
+    RoleRequest:
+      type: object
+      description: Writable fields for creating or replacing a role.
+      required:
+        - name
+      properties:
+        name:
+          type: string
+          examples:
+            - Finance tools
+          description: Role name, unique within the account (case-insensitive).
+        description:
+          type: string
+          examples:
+            - Read access to finance MCP tools
+          description: Free-text description of the role's purpose.
+        resourceGrants:
+          type: array
+          description: Resource grants this role carries. `_resourceId` values must reference resources owned by the same account.
+          items:
+            $ref: '#/components/schemas/ResourceGrant'
+  responses:
+    400-bad-request:
+      description: |
+        Bad request. The server could not understand the request because of malformed syntax or invalid parameters.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: invalid_request
+                    message: The request body failed validation.
+    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
+    403-forbidden:
+      description: |
+        Forbidden. The authenticated caller does not have permission to perform this operation.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: forbidden
+                    message: You do not have permission to access this resource.
+    422-unprocessable-entity:
+      description: |
+        Unprocessable entity. The request was well-formed but was unable to be followed due to semantic errors.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: unprocessable_entity
+                    message: The request could not be processed due to a semantic error.
+    404-not-found:
+      description: |
+        Not found. The requested resource does not exist or is not visible to the caller.
+      content:
+        application/json:
+          schema:
+            $ref: '#/components/schemas/Error'
+          examples:
+            default:
+              value:
+                errors:
+                  - code: not_found
+                    message: The requested resource was not found.
+x-enable-proxy: true
+x-internal: false