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
  /identity-governance/preferences:
    post:
      tags:
        - Management
      summary: Retrieve preferences of governance connector configurations.
      operationId: getPreferenceByPost
      description: |
        This API returns information about configuration preference of governance connectors. This API will accept
        following keys.
          <table>
            <tr>
              <td><b>Connector names</b></td>
              <td><b>Properties</b></td>
              <td><b>Description</b></td>
            </tr>
            <tr>
              <td rowspan="9">self-sign-up</td>
              <td>SelfRegistration.Enable</td>
              <td>Allow user's to self register to the system</td>
            </tr>
            <tr>
              <td>SelfRegistration.LockOnCreation</td>
              <td>Lock self registered user account until e-mail verification.</td>
            </tr>
            <tr>
              <td>SelfRegistration.Notification.InternallyManage</td>
              <td>Disable if the client application handles notification sending</td>
            </tr>
            <tr>
              <td>SelfRegistration.ReCaptcha</td>
              <td>Enable reCaptcha verification during self registration.</td>
            </tr>
            <tr>
              <td>SelfRegistration.VerificationCode.ExpiryTime</td>
              <td>Specify the expiry time in minutes for the verification link.</td>
            </tr>
            <tr>
              <td>SelfRegistration.VerificationCode.SMSOTP.ExpiryTime</td>
              <td>Specify the expiry time in minutes for the SMS OTP.</td>
            </tr>
            <tr>
              <td>SelfRegistration.CallbackRegex</td>
              <td>This prefix will be used to validate the callback URL.</td>
            </tr>
            <tr>
              <td>SelfRegistration.NotifyAccountConfirmation</td>
              <td>Enable sending notification for self sign up confirmation.</td>
            </tr>
            <tr>
              <td>SelfRegistration.ResendConfirmationReCaptcha</td>
              <td>Prompt reCaptcha verification for resend confirmation</td>
            </tr>
            <tr>
              <td rowspan="7">lite-user-sign-up</td>
              <td>LiteRegistration.Enable</td>
              <td>Allow user's to self register to the system without a password.</td>
            </tr>
            <tr>
              <td>LiteRegistration.LockOnCreation</td>
              <td>Lock self registered user account until e-mail verification.</td>
            </tr>
            <tr>
              <td>LiteRegistration.Notification.InternallyManage</td>
              <td>Disable if the client application handles notification sending</td>
            </tr>
            <tr>
              <td>LiteRegistration.ReCaptcha</td>
              <td>Enable reCaptcha verification during self registration.</td>
            </tr>
            <tr>
              <td>LiteRegistration.VerificationCode.ExpiryTime</td>
              <td>Specify the expiry time in minutes for the verification link.</td>
            </tr>
            <tr>
              <td>LiteRegistration.VerificationCode.SMSOTP.ExpiryTime</td>
              <td>Specify the expiry time in minutes for the SMS OTP.</td>
            </tr>
            <tr>
              <td>LiteRegistration.CallbackRegex</td>
              <td>This prefix will be used to validate the callback URL.</td>
            </tr>
            <tr>
              <td rowspan="6">user-email-verification</td>
              <td>EmailVerification.Enable</td>
              <td>A verification notification will be triggered during user creation.</td>
            </tr>
            <tr>
              <td>EmailVerification.LockOnCreation</td>
              <td>The user account will be locked during user creation.</td>
            </tr>
            <tr>
              <td>EmailVerification.Notification.InternallyManage</td>
              <td>Disable if the client application handles notification sending.</td>
            </tr>
            <tr>
              <td>EmailVerification.ExpiryTime</td>
              <td>Set the time span that the verification e-mail would be valid, in minutes. (For infinite validity period, set -1)</td>
            </tr>
            <tr>
              <td>EmailVerification.AskPassword.ExpiryTime</td>
              <td>Set the time span that the ask password e-mail would be valid, in minutes. (For infinite validity period, set -1)</td>
            </tr>
            <tr>
              <td>EmailVerification.AskPassword.PasswordGenerator</td>
              <td>Temporary password generation extension point in ask password feature.)</td>
            </tr>
            <tr>
            <td rowspan="2">passwordHistory</td>
            <td>passwordHistory.enable</td>
            <td>User will not be allowed to use previously used passwords.</td>
            </tr>
            <tr>
              <td>passwordHistory.count</td>
              <td>Restrict using this number of last used passwords during password update.</td>
            </tr>
            <tr>
              <td rowspan="5">passwordPolicy</td>
              <td>passwordPolicy.enable</td>
              <td>Validate user passwords against a policy</td>
            </tr>
            <tr>
              <td>passwordPolicy.min.length</td>
              <td>Minimum number of characters in the password.</td>
            </tr>
            <tr>
              <td>passwordPolicy.max.length</td>
              <td>Maximum number of characters in the password.</td>
            </tr>
            <tr>
              <td>passwordPolicy.pattern</td>
              <td>The regular expression pattern to validate the password.</td>
            </tr>
            <tr>
              <td>passwordPolicy.errorMsg</td>
              <td>This error message will be displayed when a pattern violation is detected.</td>
            </tr>
            <tr>
              <td rowspan="5">account.lock.handler</td>
              <td>account.lock.handler.enable</td>
              <td>Lock user accounts on failed login attempts</td>
            </tr>
            <tr>
              <td>account.lock.handler.On.Failure.Max.Attempts</td>
              <td>Number of failed login attempts allowed until account lock.</td>
            </tr>
            <tr>
              <td>account.lock.handler.Time</td>
              <td>Initial account lock time period in minutes. Account will be automatically unlocked after this time period.</td>
            </tr>
            <tr>
              <td>account.lock.handler.login.fail.timeout.ratio</td>
              <td>Account lock duration will be increased by this factor. Ex: Initial duration: 5m; Increment factor: 2; Next lock duration: 5 x 2 = 10m</td>
            </tr>
            <tr>
              <td>account.lock.handler.notification.manageInternally</td>
              <td>Disable if the client application handles notification sending</td>
            </tr>
            <tr>
              <td rowspan="3">sso.login.recaptcha</td>
              <td>sso.login.recaptcha.enable.always</td>
              <td>Always prompt reCaptcha verification during SSO login flow.</td>
            </tr>
            <tr>
              <td>sso.login.recaptcha.enable</td>
              <td>Prompt reCaptcha verification during SSO login flow only after the max failed attempts exceeded.</td>
            </tr>
            <tr>
              <td>sso.login.recaptcha.on.max.failed.attempts</td>
              <td>Number of failed attempts allowed without prompting reCaptcha verification.</td>
            </tr>
            <tr>
              <td rowspan="4">user-claim-update</td>
              <td>UserClaimUpdate.Email.EnableVerification</td>
              <td>Trigger a verification notification when user's email address is updated.</td>
            </tr>
            <tr>
              <td>UserClaimUpdate.Email.VerificationCode.ExpiryTime</td>
              <td>Validity time of the email confirmation link in minutes.</td>
            </tr>
            <tr>
              <td>UserClaimUpdate.MobileNumber.EnableVerification</td>
              <td>Trigger a verification SMS OTP when user's mobile number is updated.</td>
            </tr>
            <tr>
              <td>UserClaimUpdate.MobileNumber.VerificationCode.ExpiryTime</td>
              <td>Validity time of the mobile number confirmation OTP in minutes.</td>
            </tr>
            <tr>
            <td rowspan="3">suspension.notification</td>
            <td>suspension.notification.enable</td>
            <td>Lock user account after a given idle period.</td>
            </tr>
            <tr>
              <td>suspension.notification.account.disable.delay</td>
              <td>Time period in days before locking the user account.</td>
            </tr>
            <tr>
              <td>suspension.notification.delays</td>
              <td>Send warning alerts to users before locking the account, after each period. Comma separated multiple values accepted.</td>
            </tr>
            <td rowspan="2">account.disable.handler</td>
            <td>account.disable.handler.enable</td>
            <td>Allow an administrative user to disable user accounts</td>
            </tr>
            <tr>
              <td>account.disable.handler.notification.manageInternally</td>
              <td>Disable, if the client application handles notification sending</td>
            </tr>
            <tr>
              <td rowspan="20">account-recovery</td>
              <td>Recovery.Notification.Password.Enable</td>
              <td>Notification based password recovery</td>
            </tr>
            <tr>
              <td>Recovery.ReCaptcha.Password.Enable</td>
              <td>Enable reCaptcha for password recovery</td>
            </tr>
            <tr>
              <td>Recovery.Question.Password.Enable</td>
              <td>Security question based password recovery</td>
            </tr>
            <tr>
              <td>Recovery.Question.Password.MinAnswers</td>
              <td>Number of questions required for password recovery</td>
            </tr>
            <tr>
              <td>Recovery.Question.Answer.Regex</td>
              <td>Security question answer regex</td>
            </tr>
            <tr>
              <td>Recovery.Question.Answer.Uniquenes</td>
              <tdEnforce security question answer uniqueness</td>
            </tr>
            <tr>
              <td>Recovery.Question.Password.ReCaptcha.Enable</td>
              <td>rompt reCaptcha for security question based password recovery</td>
            </tr>
            <tr>
              <td>Recovery.Question.Password.ReCaptcha.MaxFailedAttempts</td>
              <td>Max failed attempts for reCaptcha</td>
            </tr>
            <tr>
              <td>Recovery.Notification.Username.Enable</td>
              <td>Username recovery</td>
            </tr><tr>
              <td>Recovery.ReCaptcha.Username.Enable</td>
              <td>Enable reCaptcha for username recovery</td>
            </tr>
            <tr>
              <td>Recovery.Notification.InternallyManage</td>
              <td>Disable if the client application handles notification sending</td>
            </tr>
            <tr>
              <td>Recovery.NotifySuccess</td>
              <td>Notify when recovery success</td>
            </tr><tr>
              <td>Recovery.Question.Password.NotifyStart</td>
              <td>Notify when security questions based recovery starts</td>
            </tr>
            <tr>
              <td>Recovery.ExpiryTime</td>
              <td>Recovery link expiry time</td>
            </tr>
            <tr>
              <td>Recovery.Notification.Password.ExpiryTime.smsOtp</td>
              <td>Expiration time of the SMS OTP code for password recovery</td>
            </tr><tr>
              <td>Recovery.Notification.Password.smsOtp.Regex</td>
              <td>Regex for SMS OTP in format [allowed characters]{length}. Supported character ranges are a-z, A-Z, 0-9.</td>
            </tr>
            <tr>
              <td>Recovery.Question.Password.Forced.Enable</td>
              <td>Force users to provide answers to security questions during sign in</td>
            </tr>
            <tr>
              <td>Recovery.Question.MinQuestionsToAnswer</td>
              <td>Force users to provide answers to security questions during sign in if user has answered lesser than this value</td>
            </tr>
            <tr>
              <td>Recovery.CallbackRegex</td>
              <td>Recovery callback URL regex</td>
            </tr><tr>
              <td>Recovery.AutoLogin.Enable</td>
              <td>User will be logged in automatically after completing the Password Reset wizard</td>
            </tr>
            <tr>
            <td rowspan="3">admin-forced-password-reset</td>
            <td>Recovery.AdminPasswordReset.RecoveryLink</td>
            <td>User gets notified with a link to reset password</td>
            </tr>
            <tr>
              <td>Recovery.AdminPasswordReset.OTP</td>
              <td>User gets notified with a one time password to try with SSO login</td>
            </tr>
            <tr>
              <td>Recovery.AdminPasswordReset.Offline</td>
              <td>An OTP generated and stored in users claims.</td>
            </tr>
          </table>

        <b>scope required:</b>
        * internal_login
      requestBody:
        content:
          application/json:
            schema:
              type: array
              example:
                - connector-name: self-sign-up
                  properties:
                    - SelfRegistration.Enable
                    - SelfRegistration.LockOnCreation
                - connector-name: user-email-verification
                  properties:
                    - EmailVerification.Enable
                    - EmailVerification.LockOnCreation
              items:
                $ref: '#/components/schemas/PreferenceSearchAttribute'
        description: This represents the connector and the properties which preferences needs to be returned.
        required: true
      responses:
        '200':
          description: Configuration preferences
          content:
            application/json:
              schema:
                type: array
                example:
                  - connector-name: self-sign-up
                    properties:
                      - name: SelfRegistration.Enable
                        value: 'false'
                      - name: SelfRegistration.LockOnCreation
                        value: 'false'
                  - connector-name: user-email-verification
                    properties:
                      - name: EmailVerification.Enable
                        value: 'true'
                      - name: EmailVerification.LockOnCreation
                        value: 'false'

                items:
                  $ref: '#/components/schemas/PreferenceResp'

        '400':
          $ref: '#/components/responses/InvalidInput'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'

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.
    Forbidden:
      description: Resource Forbidden
    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.
        meta:
          type: object
          description: Meta data properties
          $ref: '#/components/schemas/MetaRes'
    MetaRes:
      type: object
      description: Meta Data related to each property
      properties:
        type:
          type: string
          description: Data type of the property
          example: boolean
        regex:
          type: string
          description: regular expression
          example: "[a-zA-Z0-9]{6}"
        groupID:
          type: integer
          description: Group id of the property if any
          example: 0
    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'
    PreferenceSearchAttribute:
      type: object
      description: Governance connector details.
      required:
        - connector-name
      properties:
        connector-name:
          type: string
        properties:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
    Attribute:
      type: string
      description: Attribute name.
    PreferenceResp:
      type: object
      description: Governance connector property values.
      properties:
        connector-name:
          type: string
        properties:
          type: array
          items:
            $ref: '#/components/schemas/PropertyReq'
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: IDG-00000
        message:
          type: string
          example: Some Error Message
        description:
          type: string
          example: Some Error Description
        traceId:
          type: string
          example: e0fbcfeb-3617-43c4-8dd0-7b7d38e13047

