edge-api/source/management/authenticators.yml

---

paths:
  authenticators:
    get:
      summary: List authenticators
      description: |
        Returns a list of authenticators associated to identities. The resources can be sorted, filtered, and paginated.
        This endpoint requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Authenticator
      operationId: listAuthenticators
      parameters:
        - $ref: '../shared/parameters.yml#/limit'
        - $ref: '../shared/parameters.yml#/offset'
        - $ref: '../shared/parameters.yml#/filter'
      responses:
        '200':
          $ref: '../shared/authenticators.yml#/responses/listAuthenticators'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

    post:
      summary: Creates an authenticator
      description: |
        Creates an authenticator for a specific identity. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Authenticator
      operationId: createAuthenticator
      parameters:
        - name: authenticator
          in: body
          required: true
          description: A Authenticator create object
          schema:
            $ref: '../shared/authenticators.yml#/definitions/authenticatorCreate'
      responses:
        '201':
          $ref: '../shared/standard-responses.yml#/responses/createResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

  authenticators-id:
    parameters:
      - $ref: '../shared/parameters.yml#/id'
    get:
      summary: Retrieves a single authenticator
      description: Retrieves a single authenticator by id. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Authenticator
      operationId: detailAuthenticator
      responses:
        '200':
          $ref: '../shared/authenticators.yml#/responses/detailAuthenticator'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

    put:
      summary: Update all fields on an authenticator
      description: Update all fields on an authenticator by id. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Authenticator
      operationId: updateAuthenticator
      parameters:
        - name: authenticator
          in: body
          required: true
          description: 'An authenticator put object'
          schema:
            $ref: '../shared/authenticators.yml#/definitions/authenticatorUpdate'
      responses:
        '200':
          $ref: '../shared/standard-responses.yml#/responses/updateResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

    patch:
      summary: Update the supplied fields on an authenticator
      description: Update the supplied fields on an authenticator by id. Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Authenticator
      operationId: patchAuthenticator
      parameters:
        - name: authenticator
          in: body
          required: true
          description: An authenticator patch object
          schema:
            $ref: '../shared/authenticators.yml#/definitions/authenticatorPatch'
      responses:
        '200':
          $ref: '../shared/standard-responses.yml#/responses/patchResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

    delete:
      summary: Delete an Authenticator
      description: |
        Delete an authenticator by id. Deleting all authenticators for an identity will make it impossible to log in.
        Requires admin access.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Authenticator
      operationId: deleteAuthenticator
      responses:
        '200':
          $ref: '../shared/standard-responses.yml#/responses/deleteResponse'
        '400':
          $ref: '../shared/standard-responses.yml#/responses/badRequestResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'

  authenticators-id-re-enroll:
    parameters:
      - $ref: '../shared/parameters.yml#/id'
    post:
      summary: Reverts an authenticator to an enrollment
      description: |
        Allows an authenticator to be reverted to an enrollment and allows re-enrollment to occur. On success the 
        created enrollment record response is provided and the source authenticator record will be deleted. The 
        enrollment created depends on the authenticator. UPDB authenticators result in UPDB enrollments, CERT
        authenticators result in OTT enrollments, CERT + CA authenticators result in OTTCA enrollments.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Authenticator
      operationId: reEnrollAuthenticator
      parameters:
        - name: reEnroll
          in: body
          required: true
          description: A reEnrollment request
          schema:
            $ref: '#/definitions/reEnroll'
      responses:
        '201':
          $ref: '../shared/standard-responses.yml#/responses/createResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'
  authenticators-id-request-extend:
    parameters:
      - $ref: '../shared/parameters.yml#/id'
    post:
      summary: Indicate a certificate authenticator should be extended and optionally key rolled on next authentication.
      description: |
        Allows a certificate authenticator to be flagged for early extension and optionally private key rolling. 
        Connecting clients will receive flags in their API Session indicating that an early extension is request and
        a hint on whether private keys should be rolled. Clients that do not support extension or cannot roll keys
        may ignore one or both flags.
        
        If this request is made against a non-certificate based authenticator, it will return a 403-forbidden error.
      security:
        - ztSession: [ ]
        - oauth2: [ openid ]
      tags:
        - Authenticator
      operationId: requestExtendAuthenticator
      parameters:
        - name: requestExtendAuthenticator
          in: body
          required: true
          description: A request to flag a certificate authenticator for early extension/key rolling.
          schema:
            $ref: '../shared/authenticators.yml#/definitions/requestExtendAuthenticator'
      responses:
        '200':
          $ref: '../shared/standard-responses.yml#/responses/emptyResponse'
        '404':
          $ref: '../shared/standard-responses.yml#/responses/notFoundResponse'
        '403':
          $ref: '../shared/standard-responses.yml#/responses/permanentStateConflict'
        '401':
          $ref: '../shared/standard-responses.yml#/responses/unauthorizedResponse'
        '429':
          $ref: '../shared/standard-responses.yml#/responses/rateLimitedResponse'
        '503':
          $ref: '../shared/standard-responses.yml#/responses/serverUnavailableResponse'
definitions:
  reEnroll:
    type: object
    required:
      - expiresAt
    properties:
      expiresAt:
        type: string
        format: date-time