openapi: 3.0.0
info:
  version: "1.0.0"
  title: 'WSO2 Identity Server - Configurations API Definition'
  description: 'This document specifies a **RESTful API** for **WSO2 Identity Server Configurations**'
  contact:
    name: WSO2
    url: 'http://wso2.com/products/identity-server/'
    email: architecture@wso2.org
  license:
    name: Apache 2.0
    url: 'http://www.apache.org/licenses/LICENSE-2.0.html'
security:
  - OAuth2: []
  - BasicAuth: []
paths:
  /configs:
    get:
      tags:
        - Server Configs
      summary: Retrieve Server Configs
      operationId: getConfigs
      description: |
        Retrieve Server Configs
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerConfig'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
        - Server Configs
      summary: Patch Server Configs
      description: |
        Patch Server Configs. Patch operation is supported only for primary attributes (homeRealmIdentifier, idleSessionTimeoutPeriod and rememberMePeriod)
      operationId: patchConfigs
      responses:
        '200':
          description: Successful response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchRequest'
        required: true
  /configs/provisioning/inbound/scim:
    get:
      tags:
        - Server Inbound SCIM
      summary: Retrieve Server Inbound SCIM configs
      operationId: getInboundScimConfigs
      description: |
        Retrieve Server Inbound SCIM Configs
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ScimConfig'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    put:
      tags:
        - Server Inbound SCIM
      summary: Update Server Inbound SCIM configs
      operationId: updateInboundScimConfigs
      description: |
        Update Server Inbound SCIM configs
      responses:
        '200':
          description: Successful Response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ScimConfig'
        required: true
  /configs/authenticators:
    get:
      tags:
        - Local Authenticators
      summary: List local authenticators in the server
      operationId: listAuthenticators
      description: |
        List available local authenticators of the server
      parameters:
        - $ref: '#/components/parameters/typeQueryParam'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthenticatorListResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /configs/authenticators/{authenticator-id}:
    get:
      tags:
        - Local Authenticators
      summary: Get authenticator by ID
      operationId: getAuthenticator
      description: |
        By passing in the appropriate authenticator ID, you can retrieve authenticator details
      parameters:
        - name: authenticator-id
          in: path
          description: ID of an authenticator
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authenticator'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /configs/cors:
    get:
      tags:
        - CORS
      summary: Retrieve the tenant CORS configuration.
      operationId: getCORSConfiguration
      description: Retrieve the tenant CORS configuration.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CORSConfig'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
        - CORS
      summary: Patch the tenant CORS configuration.
      operationId: patchCORSConfiguration
      description: A JSONPatch as defined by RFC 6902.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CORSPatchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /configs/jwt-key-validator:
    get:
      tags:
        - Private Key JWY validation Authenticators
      summary: Retrieve the tenant private key jwt authentication configuration.
      operationId: getPrivatKeyJWTValidationConfiguration
      description: Retrieve the tenant private key jwt authentication configuration.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JWTValidatorConfig'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      tags:
        - Private Key JWY validation Authenticators
      summary: Patch the tenant private key jwt authentication configuration.
      operationId: patchPrivatKeyJWTValidationConfiguration
      description: Patch the tenant private key jwt authentication configuration.  A JSONPatch as defined by RFC 6902.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JWTKeyValidatorPatchRequest'
        required: true
      responses:
        '200':
          description: Successful Response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /configs/home-realm-identifiers:
    get:
      tags:
        - Home Realm Identifiers
      summary: Retrieve the Home Realm Identifiers.
      operationId: getHomeRealmIdentifiers
      description: Retrieve the Home Realm Identifiers.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HomeRealmIdentifiers'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /configs/schemas:
    get:
      tags:
        - Schemas
      summary: Retrieve Schemas supported By Server.
      operationId: getSchemas
      description: |
        Retrieve Schemas supported by Server.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/SchemaListItem'

        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /configs/schemas/{schema-id}:
    get:
      tags:
        - Schemas
      summary: Get Schema by ID
      operationId: getSchema
      description: |
        By passing in the appropriate schema ID, you can retrieve attributes of a schema supported by the Server.
      parameters:
        - name: schema-id
          in: path
          description: Schema ID
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schema'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
servers:
  - url: 'https://localhost:9443/t/{tenant-domain}/api/server/v1'
    variables:
      tenant-domain:
        default: carbon.super
components:
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://localhost:9443/oauth2/authorize'
          tokenUrl: 'https://localhost:9443/oauth2/token'
          scopes: {}
  parameters:
    typeQueryParam:
      in: query
      name: type
      required: false
      description: |
        Type of authenticators. Can be either 'LOCAL' or 'REQUEST_PATH'
      schema:
        type: string
  schemas:
    Error:
      type: object
      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
    ServerConfig:
      type: object
      properties:
        homeRealmIdentifiers:
          type: array
          description: "The home realm identifier for the resident identity provider"
          items:
            type: string
            example: "localhost"
        realmConfig:
          readOnly: true
          $ref: '#/components/schemas/RealmConfig'
        idleSessionTimeoutPeriod:
          type: string
          description: "The idle session timeout in minutes"
          example: "15"
          default: "15"
        rememberMePeriod:
          type: string
          description: "The remember me period in minutes"
          example: "20160"
          default: "20160"
        provisioning:
          $ref: '#/components/schemas/ProvisioningConfig'
        authenticators:
          $ref: '#/components/schemas/AuthenticatorListResponse'
        cors:
          $ref: '#/components/schemas/CORSConfig'
    RealmConfig:
      type: object
      properties:
        adminUser:
            type: string
            description: "Username of the super admin user in the system."
            example: "admin"
            readOnly: true
        adminRole:
            type: string
            description: "Name of the super admin role in the system."
            example: "Internal/admin"
            readOnly: true
        everyoneRole:
            type: string
            description: "Name of the everyone role in the system."
            example: "Internal/everyone"
            readOnly: true
    ProvisioningConfig:
      type: object
      properties:
        inbound:
          $ref: '#/components/schemas/InboundConfig'
    InboundConfig:
      type: object
      properties:
        scim:
          $ref: '#/components/schemas/ScimConfig'
    ScimConfig:
      type: object
      properties:
        provisioningUserstore:
          type: string
          description: "userstore domain name to inbound provision users and groups. This property becomes only applicable if the enableProxyMode config is set to false"
          default: "PRIMARY"
          example: "PRIMARY"
        enableProxyMode:
          type: boolean
          description: "If this property is set to true, Users/Groups are not provisioned to the user store. They are only outbound provisioned"
          example: false
          default: false
    AuthenticatorListResponse:
      type: array
      items:
        $ref: '#/components/schemas/AuthenticatorListItem'
    AuthenticatorListItem:
      type: object
      properties:
        id:
          type: string
          example: QmFzaWNBdXRoZW50aWNhdG9y
          readOnly: true
        name:
          type: string
          example: BasicAuthenticator
        displayName:
          type: string
          example: basic
        isEnabled:
          type: boolean
          default: true
          example: true
        type:
          type: string
          enum:
            - LOCAL
            - REQUEST_PATH
        tags:
          type: array
          items:
            type: string
          example: [2FA,MFA]
          readOnly: true
        self:
          type: string
          example: /t/carbon.super/api/server/v1/configs/authenticators/QmFzaWNBdXRoZW50aWNhdG9y
    Authenticator:
      type: object
      properties:
        id:
          type: string
          example: QmFzaWNBdXRoZW50aWNhdG9y
          readOnly: true
        name:
          type: string
          example: BasicAuthenticator
        displayName:
          type: string
          example: basic
        isEnabled:
          type: boolean
          default: true
        type:
          type: string
          enum:
            - LOCAL
            - REQUEST_PATH
        tags:
          type: array
          items:
            type: string
          example: [2FA,MFA]
          readOnly: true
        properties:
          type: array
          items:
            $ref: '#/components/schemas/AuthenticatorProperty'
      required:
        - name
        - displayName
    AuthenticatorProperty:
      required:
        - key
      type: object
      properties:
        key:
          type: string
          example: AuthMechanism
        value:
          type: string
          example: basic
    PatchRequest:
      type: array
      items:
        $ref: '#/components/schemas/Patch'
    Patch:
      description: A JSONPatch as defined by RFC 6902. Patch operation is supported only for root level attributes of ServerConfig.
      required:
        - operation
        - path
      properties:
        operation:
          type: string
          description: The operation to be performed
          enum:
            - ADD
            - REMOVE
            - REPLACE
          example: REPLACE
        path:
          type: string
          description: A JSON-Pointer
          example: '/idleSessionTimeoutPeriod'
        value:
          type: string
          description: The value to be used within the operations
          example: '30'
    CORSConfig:
      type: object
      properties:
        allowGenericHttpRequests:
          type: boolean
          description: If true, generic HTTP requests must be allowed to pass through the filter. Else, only valid and accepted CORS must be allowed (strict CORS filtering).
          example: true
        allowAnyOrigin:
          type: boolean
          description: If true the CORS valve must allow requests from any origin, else the origin whitelist must be consulted.
          example: false
        allowSubdomains:
          type: boolean
          description: If true, the CORS valve must allow requests from any origin which is a subdomain origin of the allowed origins.
          example: false
        supportedMethods:
          type: array
          description: The supported HTTP methods. Requests for methods not included here must be refused by the CORS filter with an HTTP 405 \"Method not allowed\" response.
          items:
            type: string
            example: GET
        supportAnyHeader:
          type: boolean
          description: If true the CORS valve must support any requested header, else the supported headers list must be consulted.
          example: false
        supportedHeaders:
          type: array
          description: The names of the supported author request headers.
          items:
            type: string
            example: Content-Type
        exposedHeaders:
          type: array
          description: The non-simple response headers that the web browser should expose to the author of the CORS request.
          items:
            type: string
            example: X-Custom-1
        supportsCredentials:
          type: boolean
          description: Whether user credentials, such as cookies, HTTP authentication or client-side certificates, are supported.
          example: true
        maxAge:
          type: number
          description: Indicates how long the results of a preflight request can be cached by the web client, in seconds. If -1 then unspecified.
          example: 3600
    JWTValidatorConfig:
      type: object
      properties:
        enableTokenReuse:
          type: boolean
          description: If true, the JTI in the JWT will be unique per the request if the previously used JWT is not already expired. JTI (JWT ID) is a claim that provides a unique identifier for the JWT.
          example: true
    CORSPatchRequest:
      type: array
      items:
        $ref: '#/components/schemas/CORSPatch'
    CORSPatch:
      type: object
      required:
        - operation
        - path
        - value
      properties:
        operation:
          type: string
          description: The operation to be performed.
          enum:
            - ADD
            - REMOVE
            - REPLACE
          example: ADD
        path:
          type: string
          description: A JSON-Pointer
          example: '/allowGenericHttpRequests'
        value:
          type: string
          description: The value to be used within the operations.
          example: '30'
    JWTKeyValidatorPatchRequest:
      type: array
      items:
        $ref: '#/components/schemas/JWTKeyValidatorPatch'
    JWTKeyValidatorPatch:
      type: object
      required:
        - operation
        - path
        - value
      properties:
        operation:
          type: string
          description: The operation to be performed.
          enum:
            - ADD
            - REMOVE
            - REPLACE
          example: ADD
        path:
          type: string
          description: A JSON-Pointer
          example: '/enableTokenReuse'
        value:
          type: boolean
          description: The value to be used within the operations.
          example: false
    HomeRealmIdentifiers:
      type: array
      description: The list of home realm identifiers.
      items:
        type: string
        example: localhost
    SchemaListItem:
      type: object
      properties:
        id:
          type: string
          example: "b0fbcfeb-3617-43c4-8dd0-7b7d38e13047"
        name:
          type: string
          example: "urn:ietf:params:scim:schemas:core:2.0"
        self:
          type: string
          example: "/t/carbon.super/api/server/v1/configs/schemas/123e4567-e89b-12d3-a456-556642440000"
    Schema:
      type: object
      properties:
        id:
          type: string
          example: "b0fbcfeb-3617-43c4-8dd0-7b7d38e13047"
        name:
          type: string
          example: "urn:ietf:params:scim:schemas:core:2.0"
        attributes:
          type: array
          description: "list of attributes available in a schema"
          items:
            type: string
            example: "urn:ietf:params:scim:schemas:core:2.0:id"
