sealgate-ai Config Perms API

openapi: 3.2.0
info:
  title: SealGate Config Perms API
  description: Open-source MCP security, aggregation, and monitoring. Self-hosted MCP proxy.
  version: 0.19.0
tags:
- name: Config Perms
paths:
  /api/v1/config-perms/run:
    post:
      summary: Run Autoconfig
      description: Generate AI permission flags on the backend with the Jev decision model, then cache results.
      operationId: run_autoconfig_api_v1_config_perms_run_post
      security:
      - HTTPBearer: []
      parameters:
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional client-generated key that makes this write operation safe to retry. Reusing the same key returns the original response instead of performing the operation a second time. Keys are scoped to the caller and expire after 24 hours.
        schema:
          type: string
          maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoconfigRunRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoconfigResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Config Perms
  /api/v1/config-perms/refine:
    post:
      summary: Refine Autoconfig
      description: Re-classify MCP elements with Jev, guided by user feedback text.
      operationId: refine_autoconfig_api_v1_config_perms_refine_post
      security:
      - HTTPBearer: []
      parameters:
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional client-generated key that makes this write operation safe to retry. Reusing the same key returns the original response instead of performing the operation a second time. Keys are scoped to the caller and expire after 24 hours.
        schema:
          type: string
          maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutoconfigRefineRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoconfigResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Config Perms
  /api/v1/config-perms/cache:
    get:
      summary: Get Autoconfig Cache
      description: Get autoconfig cache entries for the caller's org. Owner sees all.
      operationId: get_autoconfig_cache_api_v1_config_perms_cache_get
      security:
      - HTTPBearer: []
      parameters:
      - name: server
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Server
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoconfigCacheResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Config Perms
    delete:
      summary: Clear Autoconfig Cache
      description: Clear the autoconfig cache for the caller's org. Owner can specify org_id.
      operationId: clear_autoconfig_cache_api_v1_config_perms_cache_delete
      security:
      - HTTPBearer: []
      parameters:
      - name: server
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Server
      - name: org_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Org Id
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClearAutoconfigCacheResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Config Perms
  /api/v1/config-perms/review:
    get:
      summary: List Pending Reviews
      description: List auto-applied, not-yet-reviewed labels for the caller's org.
      operationId: list_pending_reviews_api_v1_config_perms_review_get
      security:
      - HTTPBearer: []
      parameters:
      - name: server
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Server
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutoLabelReviewResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Config Perms
  /api/v1/config-perms/review/accept:
    post:
      summary: Accept Auto Labels
      description: 'Mark auto-applied labels as human-reviewed.


        With ``items`` omitted, accepts every unreviewed label on the server

        ("Accept all"). With ``items``, accepts only those elements - used after

        a per-item confirm or override.'
      operationId: accept_auto_labels_api_v1_config_perms_review_accept_post
      security:
      - HTTPBearer: []
      parameters:
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional client-generated key that makes this write operation safe to retry. Reusing the same key returns the original response instead of performing the operation a second time. Keys are scoped to the caller and expire after 24 hours.
        schema:
          type: string
          maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AcceptAutoLabelsRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptAutoLabelsResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Config Perms
  /api/v1/config-perms/review/dismiss:
    post:
      summary: Dismiss Setup Card
      description: 'Permanently dismiss the Overview "Setting up " setup card.


        The card is otherwise driven by ``auto_label_pending`` and reappears on

        every page load until labeling finishes - which never happens for a server

        that is waiting on OAuth authorization the admin chooses not to grant. This

        sets a durable ``setup_card_dismissed`` marker so the server drops out of

        ``pending_label_servers``. It does not touch labeling or the auto-applied

        label review queue; re-approving the server resets the marker.'
      operationId: dismiss_setup_card_api_v1_config_perms_review_dismiss_post
      security:
      - HTTPBearer: []
      parameters:
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Org to view (Super-Owner only, read-only)
          title: Domain
        description: Org to view (Super-Owner only, read-only)
      - name: Idempotency-Key
        in: header
        required: false
        description: Optional client-generated key that makes this write operation safe to retry. Reusing the same key returns the original response instead of performing the operation a second time. Keys are scoped to the caller and expire after 24 hours.
        schema:
          type: string
          maxLength: 255
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DismissSetupCardRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DismissSetupCardResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      tags:
      - Config Perms
components:
  schemas:
    ClearAutoconfigCacheResponse:
      properties:
        cleared:
          type: integer
          title: Cleared
          description: Number of entries cleared
        server:
          anyOf:
          - type: string
          - type: 'null'
          title: Server
          description: Server filter applied
      type: object
      required:
      - cleared
      title: ClearAutoconfigCacheResponse
      description: Response for DELETE config-perms/cache.
    AutoconfigRunRequest:
      properties:
        server:
          type: string
          title: Server
          description: MCP server name
        tools:
          items:
            type: string
          type: array
          title: Tools
          description: Tool names to classify
        resources:
          items:
            type: string
          type: array
          title: Resources
          description: Resource names to classify
        prompts:
          items:
            type: string
          type: array
          title: Prompts
          description: Prompt names to classify
      type: object
      required:
      - server
      title: AutoconfigRunRequest
      description: Request body for running AI autoconfig on the backend.
    DismissSetupCardResponse:
      properties:
        server:
          type: string
          title: Server
          description: Server name
        dismissed:
          type: boolean
          title: Dismissed
          description: True if a matching server was marked dismissed (False if none matched)
      type: object
      required:
      - server
      - dismissed
      title: DismissSetupCardResponse
      description: Response for POST config-perms/review/dismiss.
    AcceptAutoLabelsRequest:
      properties:
        server:
          type: string
          title: Server
          description: MCP server name
        items:
          anyOf:
          - items:
              $ref: '#/components/schemas/AutoLabelItemRef'
            type: array
          - type: 'null'
          title: Items
          description: Specific elements to mark reviewed. Omit (null) to accept every unreviewed auto-applied label on the server.
      type: object
      required:
      - server
      title: AcceptAutoLabelsRequest
      description: Request body for POST config-perms/review/accept.
    AutoLabelReviewItem:
      properties:
        item_type:
          type: string
          title: Item Type
          description: 'Element type: tool, resource, or prompt'
        item_name:
          type: string
          title: Item Name
          description: Element name
        flags:
          additionalProperties: true
          type: object
          title: Flags
          description: Applied permission flags (trifecta booleans + acl)
        reasoning:
          anyOf:
          - type: string
          - type: 'null'
          title: Reasoning
          description: LLM's one-line explanation for why it chose these flags
        description:
          anyOf:
          - type: string
          - type: 'null'
          title: Description
          description: Element description from interface-lock metadata
      type: object
      required:
      - item_type
      - item_name
      title: AutoLabelReviewItem
      description: One auto-applied, not-yet-reviewed labelled element.
    AutoconfigRefineRequest:
      properties:
        server:
          type: string
          title: Server
          description: MCP server name
        tools:
          items:
            type: string
          type: array
          title: Tools
          description: Tool names to re-classify
        resources:
          items:
            type: string
          type: array
          title: Resources
          description: Resource names to re-classify
        prompts:
          items:
            type: string
          type: array
          title: Prompts
          description: Prompt names to re-classify
        current_flags:
          additionalProperties:
            additionalProperties: true
            type: object
          type: object
          title: Current Flags
          description: Map of '<type>:<item_name>' (e.g. 'tool:search') -> current permission flags to give the LLM as baseline. Namespacing by type avoids collisions when a tool and resource share the same name. Flat name-only keys are still accepted for back-compat.
        feedback:
          type: string
          title: Feedback
          description: User feedback/instructions to adjust classifications
      type: object
      required:
      - server
      - feedback
      title: AutoconfigRefineRequest
      description: Request body for refining AI autoconfig results with user feedback.
    AutoconfigResponse:
      properties:
        server:
          type: string
          title: Server
          description: MCP server name
        tools:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Tools
          description: Tool permission flags (includes 'reasoning' per item)
        resources:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Resources
          description: Resource permission flags
        prompts:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Prompts
          description: Prompt permission flags
        descriptions:
          additionalProperties:
            type: string
          type: object
          title: Descriptions
          description: Element name → human-readable description from interface-lock metadata
      type: object
      required:
      - server
      title: AutoconfigResponse
      description: Response from AI permission auto-configuration.
    AutoconfigCacheResponse:
      properties:
        entries:
          items:
            $ref: '#/components/schemas/AutoconfigCacheEntry'
          type: array
          title: Entries
          description: Cache entries
        count:
          type: integer
          title: Count
          description: Number of entries
        server:
          anyOf:
          - type: string
          - type: 'null'
          title: Server
          description: Server filter applied
      type: object
      required:
      - entries
      - count
      title: AutoconfigCacheResponse
      description: Response for GET config-perms/cache.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    AutoconfigCacheEntry:
      properties:
        id:
          type: integer
          title: Id
          description: Cache entry ID
        server_id:
          type: integer
          title: Server Id
          description: Server ID
        server_name:
          type: string
          title: Server Name
          description: Server name
        item_type:
          type: string
          title: Item Type
          description: Item type (tool, resource, prompt)
        item_name:
          type: string
          title: Item Name
          description: Item name
        flags:
          additionalProperties: true
          type: object
          title: Flags
          description: Permission flags
        domain:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain
          description: Domain (owner only)
      type: object
      required:
      - id
      - server_id
      - server_name
      - item_type
      - item_name
      title: AutoconfigCacheEntry
      description: A single autoconfig cache entry.
    AutoLabelReviewResponse:
      properties:
        servers:
          items:
            $ref: '#/components/schemas/AutoLabelReviewServer'
          type: array
          title: Servers
          description: Servers with pending reviews
        total:
          type: integer
          title: Total
          description: Total unreviewed labels across all servers
        pending_label_servers:
          items:
            type: string
          type: array
          title: Pending Label Servers
          description: Server names where auto_label_pending is True - the LLM labeling has not yet started or is still in progress
      type: object
      required:
      - servers
      - total
      title: AutoLabelReviewResponse
      description: Response for GET config-perms/review.
    AutoLabelItemRef:
      properties:
        item_type:
          type: string
          title: Item Type
          description: 'Element type: tool, resource, or prompt'
        item_name:
          type: string
          title: Item Name
          description: Element name
      type: object
      required:
      - item_type
      - item_name
      title: AutoLabelItemRef
      description: Reference to one labelled element inside a server.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    AutoLabelReviewServer:
      properties:
        server_name:
          type: string
          title: Server Name
          description: Server name
        server_id:
          type: integer
          title: Server Id
          description: Server ID
        items:
          items:
            $ref: '#/components/schemas/AutoLabelReviewItem'
          type: array
          title: Items
          description: Unreviewed labelled elements
      type: object
      required:
      - server_name
      - server_id
      - items
      title: AutoLabelReviewServer
      description: All unreviewed auto-applied labels for one server.
    DismissSetupCardRequest:
      properties:
        server:
          type: string
          title: Server
          description: MCP server name whose setup card to dismiss
      type: object
      required:
      - server
      title: DismissSetupCardRequest
      description: Request body for POST config-perms/review/dismiss.
    AcceptAutoLabelsResponse:
      properties:
        reviewed:
          type: integer
          title: Reviewed
          description: Number of labels marked reviewed
        server:
          type: string
          title: Server
          description: Server name
      type: object
      required:
      - reviewed
      - server
      title: AcceptAutoLabelsResponse
      description: Response for POST config-perms/review/accept.
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
    ClientBearer:
      type: http
      description: Opaque ewc_ client installation credential
      scheme: bearer
    ServiceToken:
      type: http
      description: 'A SealGate service token: `sgt_acct_...` (account token) or `sgt_org_...` (org token). Mint an account token in the dashboard.'
      scheme: bearer
    MCPGatewayOAuth:
      type: oauth2
      description: OAuth 2.1 authorization-code flow (PKCE required) against the SealGate MCP gateway's authorization server. Request only the scopes an agent needs; unrequested scopes are not granted.
      flows:
        authorizationCode:
          authorizationUrl: /oauth/authorize
          tokenUrl: /oauth/token
          refreshUrl: /oauth/token
          scopes:
            mcp: Connect to the MCP gateway and call the tools exposed by your enabled servers. Every call is still evaluated by the policy engine.
            offline_access: Issue a refresh token so the client can renew access without a new browser sign-in.