openapi: 3.0.0
info:
  description: >-
    This is the RESTful API for identity governance configurations in WSO2
    Identity Server
  version: "v1"
  title: WSO2 Identity Server - Governance connectors Admin API
  contact:
    name: WSO2 Identity Server
    url: 'https://wso2.com/identity-and-access-management'
    email: architecture@wso2.org
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
tags:
  - name: Management
    description: Secured Admin-only calls
security:
  - OAuth2: []
  - BasicAuth: []
paths:
  /identity-governance/:
    get:
      tags:
        - Management
      summary: Retrieve governance connector categories.
      operationId: getCategories
      description: |
        Retrieve governance connector categories.

        <b>Permission required:</b> <br>
          * /permission/admin/manage/identity/idpmgt/view <br>
        <b>Scope required:</b> <br>
            * internal_idp_view
      parameters:
        - $ref: '#/components/parameters/limitQueryParam'
        - $ref: '#/components/parameters/offsetQueryParam'
        - $ref: '#/components/parameters/filterQueryParam'
        - $ref: '#/components/parameters/sortQueryParam'
      responses:
        '200':
          description: Governance connector categories.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/CategoriesRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '500':
          $ref: '#/components/responses/ServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
  '/identity-governance/{category-id}':
    get:
      tags:
        - Management
      summary: Retrieve governance connectors of a category.
      operationId: getConnectorCategory
      description: |
        Retrieve governance connectors of a category. <br>
        <b>Permission required:</b> <br>
            * /permission/admin/manage/identity/idpmgt/view <br>
        <b>Scope required:</b> <br>
            * internal_idp_view
      parameters:
        - $ref: '#/components/parameters/categoryIdPathParam'
      responses:
        '200':
          description: Requested governance connector category.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CategoryRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/identity-governance/{category-id}/connectors':
    get:
      tags:
        - Management
      summary: Retrieve governance connectors of a category.
      operationId: getConnectorsOfCategory
      description: |
        Retrieve governance connectors of a category.<br>
        <b>Permission required:</b> <br>
            * /permission/admin/manage/identity/idpmgt/view <br>
        <b>Scope required:</b> <br>
            * internal_idp_view
      parameters:
        - $ref: '#/components/parameters/categoryIdPathParam'
      responses:
        '200':
          description: Requested governance connector category.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConnectorRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  '/identity-governance/{category-id}/connectors/{connector-id}':
    get:
      tags:
        - Management
      summary: Retrieve governance connector.
      operationId: getConnector
      description: |
        Retrieve governance connector.<br>
        <b>Permission required:</b> <br>
            * /permission/admin/manage/identity/idpmgt/view <br>
        <b>Scope required:</b> <br>
            * internal_idp_view
      parameters:
        - $ref: '#/components/parameters/categoryIdPathParam'
        - $ref: '#/components/parameters/connectorIdPathParam'
      responses:
        '200':
          description: Requested governance connector.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorRes'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    patch:
      tags:
        - Management
      summary: Patch governance connector.
      operationId: patchConnector
      description: |
        Patch governance connector.<br>
        <b>Permission required:</b> <br>
            * /permission/admin/manage/identity/idpmgt/update <br>
        <b>Scope required:</b> <br>
            * internal_idp_update
      parameters:
        - $ref: '#/components/parameters/categoryIdPathParam'
        - $ref: '#/components/parameters/connectorIdPathParam'
      responses:
        '200':
          $ref: '#/components/responses/OK'
        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConnectorsPatchReq'
        description: governance-connector to update
servers:
  - url: https://localhost:9443/t/{tenant-domain}/api/server/v1/
components:
  parameters:
    limitQueryParam:
      in: query
      name: limit
      required: false
      description: Maximum number of records to return.
      schema:
        type: integer
        format: int32
    offsetQueryParam:
      in: query
      name: offset
      required: false
      description: Number of records to skip for pagination.
      schema:
        type: integer
        format: int32
    filterQueryParam:
      in: query
      name: filter
      required: false
      description: Condition to filter the retrieval of records.
      schema:
        type: string
    sortQueryParam:
      in: query
      name: sort
      required: false
      description: Define the order in which the retrieved records should be sorted.
      schema:
        type: string
    categoryIdPathParam:
      in: path
      name: category-id
      required: true
      description: Id of the connector category.
      schema:
        type: string
    connectorIdPathParam:
      in: path
      name: connector-id
      required: true
      description: Id of the connector.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Unauthorized.
    ServerError:
      description: Internal Server Error.
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
    NotImplemented:
      description: Not Implemented.
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Not Found.
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
    InvalidInput:
      description: Bad Request.
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
    OK:
      description: OK.
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://localhost:9443/oauth/authorize'
          tokenUrl: 'https://localhost:9443/oauth/token'
          scopes: {}
  schemas:
    CategoriesRes:
      type: object
      description: Governance connector category response.
      properties:
        id:
          type: string
          description: Connector category id.
          example: QWNjb3VudCBNYW5hZ2VtZW50IFBvbGljaWVz
        name:
          type: string
          description: Connector category name.
          example: Account Management Policies
        self:
          type: string
          description: Path to retrieve the full connector information.
          example: /t/carbon.super/api/server/v1/identity-governance/QWNjb3VudCBNYW5hZ2VtZW50IFBvbGljaWVz
        connectors:
          type: array
          description: Connectors of the category with minimal attributes.
          items:
            $ref: '#/components/schemas/CategoryConnectorsRes'
    CategoryConnectorsRes:
      type: object
      description: Governance connector response with minimal attributes.
      properties:
        id:
          type: string
          description: Connector id.
          example: c3VzcGVuc2lvbi5ub3RpZmljYXRpb24
        self:
          type: string
          description: Path to retrieve the full connector information.
          example: /t/carbon.super/api/server/v1/identity-governance/QWNjb3VudCBNYW5hZ2VtZW50IFBvbGljaWVz/connectors/c3VzcGVuc2lvbi5ub3RpZmljYXRpb24
    CategoryRes:
      type: object
      description: Governance connector category response.
      properties:
        name:
          type: string
          description: Connector category name.
          example: Account Management Policies
        connectors:
          type: array
          description: Connectors of the category with minimal attributes.
          items:
            $ref: '#/components/schemas/ConnectorRes'
    ConnectorRes:
      type: object
      description: Governance connector response.
      properties:
        id:
          type: string
          description: Connector id.
          example: c3VzcGVuc2lvbi5ub3RpZmljYXRpb24
        name:
          type: string
          description: Connector name.
          example: suspension.notification
        category:
          type: string
          description: Connector category.
          example: Account Management Policies
        friendlyName:
          type: string
          description: Connector friendly name.
          example: Lock Idle Accounts
        order:
          type: integer
          description: Connector order.
          example: 0
        subCategory:
          type: string
          description: Connector subcategory.
          example: DEFAULT
        properties:
          type: array
          description: Define any additional properties if required.
          items:
            $ref: '#/components/schemas/PropertyRes'
    PropertyRes:
      type: object
      description: Governance connector property.
      properties:
        name:
          type: string
          description: Property name.
          example: suspension.notification.enable
        value:
          type: string
          description: Property value.
          example: 'false'
        displayName:
          type: string
          description: Property display name.
          example: Enable
        description:
          type: string
          description: Property description.
          example: Enable account suspend notifications.
    ConnectorsPatchReq:
      type: object
      description: Governance connector property patch request.
      required:
        - operation
        - properties
      properties:
        operation:
          type: string
          description: Governance connector properties patch operation.
          enum:
            - UPDATE
          example: UPDATE
        properties:
          type: array
          description: Governance connector properties to patch.
          items:
            $ref: '#/components/schemas/PropertyReq'
    PropertyReq:
      type: object
      description: Governance connector property to patch.
      required:
        - name
        - value
      properties:
        name:
          type: string
          description: Property name.
          example: suspension.notification.enable
        value:
          type: string
          description: Property value.
          example: 'false'
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: AAA-00000
        message:
          type: string
          example: Some Error Message
        description:
          type: string
          example: Some Error Description
        traceId:
          type: string
          example: e0fbcfeb-3617-43c4-8dd0-7b7d38e13047
