openapi: 3.0.0
info:
  title: AuthnFactor Meta
  description: 'Meta APIs for Identity Protection AuthnFactor'
  version: 1.0.0
servers:
  - url: 'https://id360.manageengine.com/api/v1'
    description: 'API Endpoint'
tags:
  - name: authnfactor-meta
    description: 'AuthnFactor Meta APIs'
paths:
  #AuthnFactor Meta APIs
  /meta/protection/authnfactors:
    get:
      tags:
        - authnfactor-meta
      summary: 'Get All AuthnFactors'
      description: 'The Get All AuthnFactors API can be used to get the details of all authnFactors in your account.'
      parameters:
        - $ref: '#/components/parameters/acceptHeader'
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/getAuthnfactorsResponse'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.meta.READ
  /meta/protection/authnfactors/{factor_type}:
    get:
      tags:
        - authnfactor-meta
      summary: 'Get AuthnFactor'
      description: 'The Get AuthnFactor API can be used to get the details of a specific authnFactor in your account.'
      parameters:
        - $ref: '#/components/parameters/factorType'
        - $ref: '#/components/parameters/acceptHeader'
      responses:
        '200':
          description: 'OK'
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/authnfactorResource'
        '401':
          description: 'Unauthorized'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/unauthorized'
        '404':
          description: 'Not Found'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/authnfactorNotFound'
        '500':
          description: 'Internal Server Error'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/serverError'
      security:
        - Zoho_Auth:
            - id360.meta.READ

components:
  parameters:
    acceptHeader:
      name: Accept
      in: header
      schema:
        type: string
      description: 'Accept header for the API'
      required: false
      example: 'application/json'
    factorType:
      name: factor_type
      in: path
      required: true
      description: 'The type of the authnFactor to be fetched'
      example: 'EmailAuthenticator'
      schema:
        type: string
  schemas:
    unauthorized:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '00000101'
            title:
              type: string
              example: 'Unauthorized'
            detail:
              type: string
              example: 'The OAuth token is invalid.'
    serverError:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '00000000'
            title:
              type: string
              example: 'Internal Server Error'
            detail:
              type: string
              example: 'An unexpected internal error has occurred on the server. Please try again later.'

    # Resource representing an AuthnFactor
    authnfactorResource:
      type: object
      properties:
        factor_type:
          type: string
          description: Authenticator name
          example: "EmailAuthenticator"
          readOnly: true
        display_name:
          type: string
          description: Authenticator display name.
          example: "Email Verification"
          readOnly: true
        display_order:
          type: integer
          description: Authenticator display Order.
          example: 1
          readOnly: true
        is_custom_factor:
          type: boolean
          description: >
            To check whether the authenticator is custom factor or not
            <br>
            Note: will be true for CTOTP and false for other authenticator
          example: true
          readOnly: true
        factor_details:
          readOnly: true
          $ref: '#/components/schemas/factorDetails'
    factorDetails:
      type: object
      properties:
        fido_rp_id:
          type: string
          description: FIDO2 Passkeys Replying Party ID
          example: "id360.manageengine.com"
        saml_provider_list:
          type: array
          description: SAML Identity Providers List
          items:
            type: object
            properties:
              name:
                type: string
                description: Name of the SAML identity provider
                example: "okta"
              label:
                type: string
                description: Label of the SAML identity provider
                example: "Okta"
          example:
            - name: "okta"
              label: "Okta"
            - name: "onelogin"
              label: "Onelogin"
    getAuthnfactorsResponse:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/authnfactorResource'
          example:
            - factor_type: "EmailAuthenticator"
              display_name: "Email Verification"
              is_custom_factor: false
              display_order: 1
            - factor_type: "FIDOAuthenticator"
              display_name: "FIDO2 Passkeys"
              is_custom_factor: false
              display_order: 2
            - factor_type: "MicrosoftAuthenticator"
              display_name: "Microsoft Authenticator"
              is_custom_factor: false
              display_order: 3
            - factor_type: "GoogleAuthenticator"
              display_name: "Google Authenticator"
              is_custom_factor: false
              display_order: 4
            - factor_type: "SQAAuthenticator"
              display_name: "SQA Authenticator"
              is_custom_factor: false
              display_order: 5
            - factor_type: "SMSAuthenticator"
              display_name: "SMS Verification"
              is_custom_factor: false
              display_order: 6
            - factor_type: "DUOAuthenticator"
              display_name: "Duo"
              is_custom_factor: false
              display_order: 7
            - factor_type: "CustomTOTPAuthenticator"
              display_name: "Custom TOTP Authenticator"
              is_custom_factor: true
              display_order: 8
            - factor_type: "ZohoOneAuthAuthenticator"
              display_name: "Zoho OneAuth TOTP"
              is_custom_factor: false
              display_order: 9
            - factor_type: "SAMLAuthenticator"
              display_name: "SAML Authenticator"
              is_custom_factor: false
              display_order: 10
            - factor_type: "SmartCardAuthenticator"
              display_name: "Smart Card Authentication"
              is_custom_factor: false
              display_order: 11
    authnfactorNotFound:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              example: '---'
            title:
              type: string
              example: 'AuthnFactor Not Found'
            detail:
              type: string
              example: 'This AuthnFactor type does not exist.'
  securitySchemes:
    Zoho_Auth:
      type: oauth2
      x-authorization-example: 'Zoho-oauthtoken 1000.41d9f2cfbd1b7a8f9e314b7aff7bc2d1.8fcc9810810a216793f385b9dd6e125f'
      flows:
        authorizationCode:
          authorizationUrl: 'https://accounts.zoho.com/oauth/v2/auth'
          tokenUrl: 'https://accounts.zoho.com/oauth/v2/token'
          scopes:
            idmpod.meta.read: 'Read Meta data from the account'