openapi: 3.0.0
info:
  title: WSO2 Identity Server - Organization Configuration API Definition
  description: This document specifies a **RESTful API** for **WSO2 Identity Server Organization Configurations**
  contact:
    name: WSO2
    url: http://wso2.com/products/identity-server/
    email: iam-dev@wso2.org
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  version: "v1"
servers:
  - url: 'https://localhost:9443/o/{organization-domain}/api/server/v1'
    variables:
      organization-domain:
        default: 10084a8d-113f-4211-a0d5-efe36b082211
security:
  - OAuth2: []
  - BasicAuth: []

paths:
  /organization-configs/discovery:
    get:
      tags:
        - Discovery
      summary: Get organization discovery configuration.
      description: |
        This API facilitates the retrieval of discovery configuration of the primary organization. <br>
          <b>Permission required:</b> <br>
            * /permission/admin/manage/identity/configmgt/view <br>
          <b>Scope required:</b> <br>
            * internal_config_mgt_view
      operationId: getDiscoveryConfig
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Config'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
    post:
      tags:
        - Discovery
      summary: Add organization discovery configuration.
      description: |
        This API provides the capability to add discovery configuration for the primary organization. <br>
        
        The `defaultParam` attribute sets the discovery parameter used to resolve the organization. (e.g., `orgHandle`, `orgName`) <br>
        
          <b>Scope(Permission) required:</b> <br>
            * internal_config_mgt_add
      operationId: createDiscoveryConfig
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Config'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Config'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '500':
          $ref: '#/components/responses/ServerError'
    put:
      tags:
        - Discovery
      summary: Update organization discovery configuration.
      description: |
        This API provides the capability to update discovery configuration of the primary organization. <br>
        
        The `defaultParam` attribute sets the discovery parameter used to resolve the organization. (e.g., `orgHandle`, `orgName`) <br>
        
          <b>Scope(Permission) required:</b> <br>
            * internal_config_mgt_update
      operationId: updateDiscoveryConfig
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Config'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Config'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'
    delete:
      tags:
        - Discovery
      summary: Delete organization discovery configuration.
      description: |
        This API provides the capability to delete discovery configuration of the primary organization.<br>
          <b>Permission required:</b> <br>
            * /permission/admin/manage/identity/configmgt/delete <br>
          <b>Scope required:</b> <br>
            * internal_config_mgt_delete
      operationId: deleteDiscoveryConfig
      responses:
        '204':
          $ref: '#/components/responses/NoContent'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/ServerError'

components:
  schemas:
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: OCM-00000
          description: An error code.
        message:
          type: string
          example: Some Error Message
          description: An error message.
        description:
          type: string
          example: Some Error Description
          description: An error description.
        traceId:
          type: string
          example: e0fbcfeb-3617-43c4-8dd0-7b7d38e13047
          description: An error trace identifier.

    Config:
      type: object
      required:
        - properties
      properties:
        properties:
          type: array
          items:
            $ref: '#/components/schemas/Properties'
    Properties:
      required:
        - key
        - value
      type: object
      properties:
        key:
          type: string
          example: emailDomain.enable
        value:
          type: string
          example: true

  responses:
    BadRequest:
      description: Invalid input in the request.
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: Requested resource is not found.
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: Resource already exists.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NoContent:
      description: No content.
    Unauthorized:
      description: Authentication information is missing or invalid.
    Forbidden:
      description: Access forbidden.
    ServerError:
      description: Internal server error.
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/Error'

  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://localhost:9443/oauth2/authorize
          tokenUrl: https://localhost:9443/oauth2/token
          scopes: {}
