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/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'

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
        name:
          type: string
          example: BasicAuthenticator
        displayName:
          type: string
          example: basic
        isEnabled:
          type: boolean
          example: true
        type:
          type: string
          enum:
            - LOCAL
            - FEDERATED
        image:
          type: string
          example: basic-authenticator-logo-url
        description:
          type: string
          example: The basic authenticator.
        tags:
          type: array
          items:
            type: string
          example: [2FA, MFA]
        self:
          type: string
          example: /t/carbon.super/api/server/v1/configs/authenticators/eDUwOUNlcnRpZmljYXRlQXV0aGVudGljYXRvcg

  #-----------------------------------------------------
  # 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: {}
