openapi: 3.0.0
info:
  version: "v1"
  title: 'WSO2 Identity Server - Authenticators API Definition'
  description: 'This document specifies a **RESTful API** for **WSO2 Identity Server Authenticators**'
  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'
servers:
  - url: 'https://localhost:9443/t/{tenant-domain}/api/server/v1'
    variables:
      tenant-domain:
        default: carbon.super
security:
  - OAuth2: []
  - BasicAuth: []

paths:
  /authenticators:
    get:
      tags:
        - Authenticators
      summary: List all authenticators in the server
      description: List all authenticators in the server
      parameters:
        - $ref: '#/components/parameters/filterQueryParam'
        - $ref: '#/components/parameters/limitQueryParam'
        - $ref: '#/components/parameters/offsetQueryParam'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Authenticators'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
        '501':
          $ref: '#/components/responses/NotImplemented'
  /authenticators/{authenticator-id}/connected-apps:
    get:
      tags:
        - Connected apps of local authenticators
      summary: Get connected apps by authenticator ID
      operationId: getConnectedAppsOfLocalAuthenticator
      description: |
        By passing in the appropriate authenticator ID, you can retrieve connected app details
      parameters:
        - $ref: '#/components/parameters/limitQueryParam'
        - $ref: '#/components/parameters/offsetQueryParam'
        - 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/ConnectedApps'
        '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'
  /authenticators/meta/tags:
    get:
      tags:
        - Authenticators
      summary: List all authenticator tags
      description: List all authenticator tags
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Tags'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/ServerError'
  /authenticators/custom:
    post:
      tags:
        - User defined local authenticators
      summary: |
        Create a new user defined local authenticator.
      description: |
        This API provides the capability to create a new user defined local authenticator. <br>
        <b>Permission required:</b> <br>
            * /permission/admin/manage/custom_authenticator/create <br>
        <b>Scope required:</b> <br>
            * internal_custom_authenticator_create <br>
      operationId: addUserDefinedLocalAuthenticator
      responses:
        '201':
          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
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserDefinedLocalAuthenticatorCreation'
        description: This represents the user defined local authenticator to be created.
        required: true
  /authenticators/custom/{authenticator-id}:
    put:
      tags:
        - User defined local authenticators
      summary: |
        Update a user defined local authenticator.
      description: |
        This API provides the capability to update a user defined local authenticator configurations. <br>
        <b>Permission required:</b> <br>
            * /permission/admin/manage/custom_authenticator/update <br>
        <b>Scope required:</b> <br>
            * internal_custom_authenticator_update <br>
      operationId: updateUserDefinedLocalAuthenticator
      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
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserDefinedLocalAuthenticatorUpdate'
        description: This represents the user defined local authenticator to be created.
        required: true
    delete:
      tags:
        - User defined local authenticators
      summary: |
        Delete a user defined local authenticator.
      description: |
        This API provides the capability to delete a user defined local authenticators. <br>
        <b>Permission required:</b> <br>
            * /permission/admin/manage/custom_authenticator/delete <br>
        <b>Scope required:</b> <br>
            * internal_custom_authenticator_delete <br>
      operationId: deleteUserDefinedLocalAuthenticator
      parameters:
        - name: authenticator-id
          in: path
          description: ID of an authenticator
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Successful response
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '500':
          description: Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  parameters:
    filterQueryParam:
      in: query
      name: filter
      required: false
      description: >
        Condition to filter the retrieval of records.
        Only supports filtering based on the 'tag' and 'name' attribute.
        For local authenticators and request path authenticators, the 'displayName' is considered as the 'name' attribute during filtering.
        The 'name' attribute only supports 'eq' and 'sw operations. Filtering with multiple 'name' attributes is not supported.
        The 'tag' attribute only supports 'eq' operation. Filtering with multiple 'tag' attributes is supported with only 'or' as the complex query operation.
        E.g. /configs/authenticators?filter=name+sw+fi+and+(tag+eq+2FA+or+tag+eq+MFA)
      schema:
        type: string
    limitQueryParam:
      in: query
      name: limit
      description: >
        Maximum number of records to return. _<b>This option is not yet
        supported.<b>_
      schema:
        type: integer
        format: int32
        minimum: 0
    offsetQueryParam:
      in: query
      name: offset
      description: >
        Number of records to skip for pagination. _<b>This option is not yet
        supported.<b>_
      schema:
        type: integer
        format: int32
        minimum: 0
  schemas:
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          example: AUT-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.
    Tags:
      type: array
      description: The list of tags available for authenticators.
      items:
        type: string
      example: [2FA, MFA]
    Authenticators:
      type: array
      items:
        $ref: '#/components/schemas/Authenticator'
    Authenticator:
      type: object
      properties:
        id:
          type: string
          example: QmFzaWNBdXRoZW50aWNhdG9y
          readOnly: true
        name:
          type: string
          example: BasicAuthenticator
        displayName:
          type: string
          example: basic
        isEnabled:
          type: boolean
          example: true
        definedBy:
          type: string
          enum:
            - SYSTEM
            - USER
          readOnly: true
        type:
          type: string
          enum:
            - LOCAL
            - FEDERATED
          readOnly: true
        image:
          type: string
          example: basic-authenticator-logo-url
        description:
          type: string
          example: The basic authenticator.
        tags:
          type: array
          items:
            type: string
          example: [2FA, MFA]
          readOnly: true
        self:
          type: string
          example: /t/carbon.super/api/server/v1/configs/authenticators/eDUwOUNlcnRpZmljYXRlQXV0aGVudGljYXRvcg
    UserDefinedLocalAuthenticatorCreation:
      description: This represents the configuration for creating the user defined local authenticator.
      type: object
      properties:
        name:
          type: string
          example: CustomAuthenticator
        id:
          type: string
          example: Q3VzdG9tQXV0aGVudGljYXRvcg==
        displayName:
          type: string
          example: Custom auth
        isEnabled:
          type: boolean
          example: true
        authenticationType:
          type: string
          enum:
            - IDENTIFICATION
            - VERIFICATION
        image:
          type: string
          example: https://custom-authenticator-logo-url
        description:
          type: string
          example: The user defined custom local authenticator.
        endpoint:
          $ref: '#/components/schemas/Endpoint'
      required:
        - name
        - displayName
        - isEnabled
        - endpoint
    UserDefinedLocalAuthenticatorUpdate:
      description: TThis represents the configuration for updating user defined local authenticator.
      type: object
      properties:
        displayName:
          type: string
          example: Custom auth
        isEnabled:
          type: boolean
          example: true
        image:
          type: string
          example: https://custom-authenticator-logo-url
        description:
          type: string
          example: The user defined custom local authenticator.
        endpoint:
          $ref: '#/components/schemas/Endpoint'
      required:
        - name
        - displayName
        - isEnabled
        - endpoint
    Endpoint:
      type: object
      properties:
        uri:
          type: string
          example: https://abc.com/token
          pattern: '^https?://.+'
        authentication:
          $ref: '#/components/schemas/AuthenticationType'
        allowedHeaders:
          type: array
          description: List of HTTP headers to forward to the extension.
          items:
            type: string
          example: [ "x-geo-location", "host"]
        allowedParameters:
          type: array
          description: List of parameters to forward to the extension.
          items:
            type: string
          example: [ "device-id"]
    AuthenticationType:
      type: object
      required:
        - type
        - properties
      properties:
        type:
          type: string
          enum:
            - NONE
            - BEARER
            - API_KEY
            - BASIC
          example: BASIC
        properties:
          type: object
          additionalProperties: true
          example:
            username: "auth_username"
            password: "auth_password"
    ConnectedApps:
      type: object
      properties:
        totalResults:
          type: integer
          example: 10
        startIndex:
          type: integer
          example: 1
        count:
          type: integer
          example: 10
        links:
          type: array
          items:
            $ref: '#/components/schemas/Link'
          example:
            [
              {
                "href": "authenticator/123e4567-e89b-12d3-a456-556642440000/connected-apps?offset=50&limit=10",
                "rel": "next"
              },
              {
                "href": "authenticator/provider/123e4567-e89b-12d3-a456-556642440000/connected-apps?offset=30&limit=10",
                "rel": "previous"
              }
            ]
        connectedApps:
          type: array
          items:
            $ref: '#/components/schemas/ConnectedApp'
    ConnectedApp:
      type: object
      properties:
        appId:
          type: string
          example: app-id
        self:
          type: string
          example: /t/org/api/server/v1/applications/c74d74b2-cb62-4abd-ad66-6c45daeb561c
    Link:
      type: object
      properties:
        href:
          type: string
          description: Path to the target resource.
          example: >-
            '/t/carbon.super/api/server/v1/authenticators/394b8adcce24c64a8a09a8d80abf8c337bd253de'
        rel:
          type: string
          description: Describes how the current context is related to the target resource.
          example: authenticators
      readOnly: true
  #-----------------------------------------------------
  # Descriptions of Authenticators API responses.
  #-----------------------------------------------------
  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'
    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'
    NotImplemented:
      description: Not Implemented.
      content:
        'application/json':
          schema:
            $ref: '#/components/schemas/Error'
  #-----------------------------------------------------
  # Applicable authentication mechanisms.
  #-----------------------------------------------------
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: 'https://localhost:9443/oauth2/authorize'
          tokenUrl: 'https://localhost:9443/oauth2/token'
          scopes: {}
