Janssen FIDO2 API

# raw swagger spec link:
# https://raw.githubusercontent.com/JanssenProject/jans-fido2/master/docs/jansFido2Swagger.yaml
# https://gluu.org/swagger-ui/?url=https://raw.githubusercontent.com/JanssenProject/jans-fido2/master/docs/jansFido2Swagger.yaml
openapi: 3.0.1
info:
  title: Janssen Fido2
  description: Janssen Fido2 - FIDO 2.0 is an open authentication standard that enables leveraging common devices to authenticate to online services in both mobile and desktop environments.
  contact:
    name: Contact
    url: https://github.com/JanssenProject/jans/discussions
  license:
    name: License
    url: https://github.com/JanssenProject/jans/blob/main/LICENSE
  version: "OAS Version"
servers:
  - url: https://jans.local.io
tags:
  - name: About
    description: Janssen includes a FIDO2 component to implement a two-step, two-factor authentication (2FA) with username / password as the first step, and any FIDO2 device as the second step.
  - name: FIDO2 configuration
  - name: FIDO2 Assertion
  - name: FIDO2 Attestation
  - name: FIDO2 Metrics
    description: Metrics and analytics API for FIDO2/Passkey operations (registrations, authentications, adoption, performance, devices, errors, trends).
  - name: FIDO2 Trust
    description: Read-only visibility into the attestation policy the server is applying. Diagnostics only — these endpoints never change attestation behaviour.
paths:
  /jans-fido2/restv1/configuration:
    get:
      tags:
        - FIDO2 configuration
      summary: FIDO2 configuration
      description: FIDO2 configuration
      operationId: get-fido2-configuration
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                title: FIDO2 configuration
                description: FIDO2 configuration.
                required:
                  - version
                  - issuer
                  - attestation
                properties:
                  version:
                    type: string
                    description: The version of the FIDO2 U2F core protocol to which this server conforms. The value MUST be the string 1.0.
                  issuer:
                    type: string
                    description: A URI indicating the party operating the FIDO U2F server.
                  attestation:
                    type: array
                    items:
                      type: object
                      description: list of fido2 attestation endpoints
                      properties:
                        base_path:
                          type: string
                          description: fido2 attestation endpoint
                        options_endpoint:
                          type: string
                          description: fido2 attestation options endpoint
                        result_endpoint:
                          type: string
                          description: fido2 attestation result endpoint
                  assertion:
                    type: array
                    items:
                      type: object
                      description: list of fido2 assertion endpoints
                      properties:
                        base_path:
                          type: string
                          description: fido2 assertion endpoint
                        options_endpoint:
                          type: string
                          description: fido2 assertion options endpoint
                        result_endpoint:
                          type: string
                          description: fido2 assertion result endpoint
        403:
          $ref: '#/components/responses/AccessDenied'
        406:
          $ref: '#/components/responses/NotAcceptable'
        500:
          $ref: '#/components/responses/InternalServerError'
  /jans-fido2/restv1/assertion/options:
    post:
      tags:
        - FIDO2 Assertion
      summary: FIDO2 Assertion Options
      description: FIDO2 Assertion Options
      operationId: options
      requestBody:
        content:
          application/json:
            schema:
              title: AssertionOptions
              description: An object that contains the extensions to enable, and the options to use for each of them.
              type: object
              required:
                - username
              properties:
                username:
                  type: string
                userVerification:
                  type: string
                documentDomain:
                  type: string
                extensions:
                  type: string
                session_id:
                  type: string
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                title: AssertionOptionsResponse
                type: object
                required:
                  - challenge
                  - user
                  - allowCredentials
                  - userVerification
                  - extensions
                properties:
                  challenge:
                    type: string
                    description: Websafe-base64 encoding of the challenge.
                  user:
                    type: string
                    description: username
                  allowCredentials:
                    type: array
                    items:
                      type: string
                    example:
                      - type
                      - transports
                      - id
                  userVerification:
                    type: string
                  extensions:
                    type: object
                  rpId:
                    type: string
                    description: Document domain.
                  status:
                    type: string
                  errorMessage:
                    type: string
        403:
          $ref: '#/components/responses/AccessDenied'
        500:
          $ref: '#/components/responses/InternalServerError'
  /jans-fido2/restv1/assertion/result:
    post:
      tags:
        - FIDO2 Assertion
      summary: FIDO2 Assertion Result - Parses and validates an assertion response from the client.
      description: FIDO2 Assertion Result.
      operationId: result
      requestBody:
        content:
          application/json:
            schema:
              title: AssertionOptions
              type: object
              required:
                - id
                - type
                - response
                - rawId
              properties:
                id:
                  type: string
                  description: The base64url encoded id
                type:
                  type: string
                  example:
                    - public-key
                rawId:
                  type: string
                  description: The base64url encoded rawId returned by the client. If res.rawId is missing, res.id will be used instead. If both are missing an error will be thrown.
                response:
                  type: object
                  properties:
                    userHandle:
                      type: string
                      description: The base64url encoded userHandle returned by the client. May be null or an empty string.
                    clientDataJSON:
                      type: string
                      description: The base64url encoded clientDataJSON returned by the client.
                    authenticatorData:
                      type: string
                      description: The base64url encoded authenticator Data. May be null or an empty string.
                    signature:
                      type: string
                      description: To verify signature.
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                title: AssertionVerifyResponse
                type: object
                required:
                  - status
                properties:
                  status:
                    type: string
                  errorMessage:
                    type: string
                  authenticatedCredentials:
                    type: object
                    properties:
                      type:
                        type: string
                      id:
                        type: string
                      transports:
                        type: array
                        description: list of transports.
                        items:
                          type: string
                        example:
                          - net
                          - qr
                          - usb
        403:
          $ref: '#/components/responses/AccessDenied'
        500:
          $ref: '#/components/responses/InternalServerError'


  /jans-fido2/restv1/attestation/options:
    post:
      tags:
        - FIDO2 Attestation
      summary: Create new registration.
      description: Create new registration.
      operationId: attestation-options
      requestBody:
        content:
          application/json:
            schema:
              title: AttestationOptions
              description: An object containing various options for the option creation
              type: object
              required:
                - username
                - displayName
                - attestation
              properties:
                username:
                  type: string
                displayName:
                  type: string
                attestation:
                  type: string
                  format: enum
                   - direct
                   - indirect
                   - none
                documentDomain:
                  type: string
                timeout:
                  type: integer
                extensions:
                  type: object
                authenticatorSelection:
                  type: object
                  properties:
                   authenticatorAttachment:
                     type: string
                     format: enum
                       - platform
                       - cross-platform
                   userVerification:
                     type: string
                     format: enum
                       - direct
                       - indirect
                       - none
                   requireResidentKey:
                     type: boolean
      responses:
        200:
          description: OK
          content:
            application/json:
              schema:
                title: CredentialCreationOptions
                type: object
                properties:
                  attestation:
                    type: string
                    format: enum
                     - direct
                     - indirect
                     - none
                  authenticatorSelection:
                    type: object
                    properties:
                      authenticatorAttachment:
                        type: string
                        format: enum
                         - platform
                         - cross-platform
                      userVerification:
                        type: string
                        format: enum
                         - required
                         - preferred
                         - discouraged
                      requireResidentKey:
                        type: boolean
                  challenge:
                    type: string
                    description: The base64url encoded challenge that was sent to the client, as generated by assertionOptions.
                  pubKeyCredParams:
                    type: object
                    properties:
                     type:
                       type: string
                     alg:
                       type: string
                  rp:
                    type: object
                    description: RP credentials
                    properties:
                     name:
                       type: string
                     id:
                       type: string
                  username:
                    type: string
                  displayName:
                    type: string
                  user:
                    type: object
                    description: User object
                    properties:
                      id:
                        type: string
                      name:
                        type: string
                      displayName:
                        type: string
                  excludeCredentials:
                    type: object
                    properties:
                      type:
                        type: string
                      id:
                        type: string
                  timeout: 
                    type: integer
                  extensions:
                    type: array
                    items:
                      type: string
                  status:
                    type: string
                  errorMessage:
                    type: string
        403:
          $ref: '#/components/responses/AccessDenied'
        500:
          $ref: '#/components/responses/InternalServerError'
  /jans-fido2/restv1/attestation/result:
    post:
      tags:
        - FIDO2 Attestation
      summary: FIDO2 attestation result.
      description: FIDO2 attestation result
      operationId: attestation-result
      requestBody:
        content:
          application/json:
            schema:
              title: AttestationOptions
              description: An object containing various options for the option creation
              type: object
              required:
                - id
                - type
                - response
              properties:
                id:
                  type: string
                  description: base64url encoded
                type:
                  type: string
                  enum: 
                    - public-key
                response:
                  type: object
                  required:
                    - clientDataJSON
                    - attestationObject
                  properties:
                    attestationObject:
                      type: string
                      description: base64url encoded
                    clientDataJSON:
                      type: object
                      description: The base64url encoded clientDataJSON returned by the client
                      required:
                        - challenge
                        - origin
                        - type
                      properties:
                        type:
                          type: string
                          enum: 
                            - webauthn.create
                        origin:
                          type: string
                        challenge:
                          type: string
                        tokenBinding:
                          type: object
                          required:
                            - status
                          properties:
                            status:
                              type: string
                            id:
                              type: string
                    clientExtensionResults:
                      type: array
                      items:
                        type: string
      responses:        
        200:
          description: OK
          content:
            application/json:
              schema:
                title: Fido2RegistrationData
                type: object
                properties:
                  createdCredentials:
                    type: object
                    properties:
                      createdDate:
                        type: string
                        format: date-time
                      updatedDate:
                        type: string
                        format: date-time
                      createdBy:
                        type: string
                      updatedBy:
                        type: string
                      username:
                        type: string
                      domain:
                        type: string
                      userId:
                        type: string
                      challenge:
                        type: string
                      attestationRequest:
                        type: string
                      attestationResponse:
                        type: object
                        properties:
                          type:
                            type: string
                            enum:
                              - public-key
                          id:
                            type: string
                          response:
                            type: object
                            required:
                              - attestationObject
                              - clientDataJSON
                            properties:
                              attestationObject:
                                type: string
                              clientDataJSON:
                                type: string
                              clientExtensionResults:
                                type: array
                                items:
                                  type: string
                      uncompressedECPoint:
                        type: string
                      publicKeyId:
                        type: string
                      type:
                        type: string
                        enum:
                          - public-key
                      status:
                        type: string
                        enum:
                          - registered
                      counter:
                        type: integer
                      attestationType:
                        type: string
                      signatureAlgorithm:
                        type: integer
                      applicationId:
                        type: string
                      authenticatorSelection:
                        type: object
                        properties:
                          authenticatorAttachment:
                            type: string
                            format: enum
                             - platform
                             - cross-platform
                          userVerification:
                            type: string
                            format: enum
                             - required
                             - preferred
                             - discouraged
                          requireResidentKey:
                            type: boolean
                  errorMessage:
                    type: string
                  status:
                    type: string
        403:
          $ref: '#/components/responses/AccessDenied'
        500:
          $ref: '#/components/responses/InternalServerError'

  # ---------------------------------------------------------------------------
  # FIDO2 Metrics API (GitHub Issue #11922)
  # ---------------------------------------------------------------------------
  /jans-fido2/restv1/metrics/entries:
    get:
      tags:
        - FIDO2 Metrics
      summary: Get metrics entries
      description: Returns all raw metric entries between startTime and endTime (ISO 8601 UTC). Use for event-level detail or custom analysis.
      operationId: get-metrics-entries
      parameters:
        - name: startTime
          in: query
          required: true
          schema:
            type: string
            example: "2026-01-01T00:00:00"
          description: Start time (ISO 8601, UTC).
        - name: endTime
          in: query
          required: true
          schema:
            type: string
            example: "2026-01-01T23:59:59"
          description: End time (ISO 8601, UTC).
      responses:
        200:
          description: List of metric entries.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MetricsEntry'
        400:
          $ref: '#/components/responses/InvalidRequest'
        403:
          $ref: '#/components/responses/AccessDenied'
        500:
          $ref: '#/components/responses/InternalServerError'
  /jans-fido2/restv1/metrics/entries/user/{userId}:
    get:
      tags:
        - FIDO2 Metrics
      summary: Get metrics entries for a user
      description: Returns metric entries for a single user (by userId/inum) in the given time range. Unknown or invalid userId returns 200 with an empty array (consistent with other metrics endpoints); 404 is not used.
      operationId: get-metrics-entries-by-user
      parameters:
        - name: userId
          in: path
          required: true
          schema:
            type: string
          description: User internal ID (inum).
        - name: startTime
          in: query
          required: true
          schema:
            type: string
          description: Start time (ISO 8601, UTC).
        - name: endTime
          in: query
          required: true
          schema:
            type: string
          description: End time (ISO 8601, UTC).
      responses:
        200:
          description: List of metric entries for the user.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MetricsEntry'
        400:
          $ref: '#/components/responses/InvalidRequest'
        403:
          $ref: '#/components/responses/AccessDenied'
        500:
          $ref: '#/components/responses/InternalServerError'
  /jans-fido2/restv1/metrics/entries/operation/{operationType}:
    get:
      tags:
        - FIDO2 Metrics
      summary: Get metrics entries by operation type
      description: Returns metric entries filtered by operation type (REGISTRATION or AUTHENTICATION).
      operationId: get-metrics-entries-by-operation
      parameters:
        - name: operationType
          in: path
          required: true
          schema:
            type: string
            enum:
              - REGISTRATION
              - AUTHENTICATION
          description: Operation type filter.
        - name: startTime
          in: query
          required: true
          schema:
            type: string
          description: Start time (ISO 8601, UTC).
        - name: endTime
          in: query
          required: true
          schema:
            type: string
          description: End time (ISO 8601, UTC).
      responses:
        200:
          description: List of metric entries for the operation type.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MetricsEntry'
        400:
          $ref: '#/components/responses/InvalidRequest'
        403:
          $ref: '#/components/responses/AccessDenied'
        500:
          $ref: '#/components/responses/InternalServerError'
  /jans-fido2/restv1/metrics/aggregations/{aggregationType}:
    get:
      tags:
        - FIDO2 Metrics
      summary: Get aggregations
      description: Returns pre-computed aggregation records (one per period) that overlap the given time range.
      operationId: get-metrics-aggregations
      parameters:
        - name: aggregationType
          in: path
          required: true
          schema:
            type: string
            enum:
              - HOURLY
              - DAILY
              - WEEKLY
              - MONTHLY
          description: Aggregation granularity.
        - name: startTime
          in: query
          required: true
          schema:
            type: string
          description: Start time (ISO 8601, UTC).
        - name: endTime
          in: query
          required: true
          schema:
            type: string
          description: End time (ISO 8601, UTC).
      responses:
        200:
          description: List of aggregation records.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/MetricsAggregation'
        400:
          $ref: '#/components/responses/InvalidRequest'
        403:
          $ref: '#/components/responses/AccessDenied'
        500:
          $ref: '#/components/responses/InternalServerError'
  /jans-fido2/restv1/metrics/aggregations/{aggregationType}/summary:
    get:
      tags:
        - FIDO2 Metrics
      summary: Get aggregation summary
      description: >-
        Returns a single summary over all aggregations in the time range (totals and average success
        rates). Reads stored aggregations, which are computed once for their period and never
        recalculated, so periods aggregated before 2.4.0 still carry the duration and device figures
        computed at the time. Read current latency from analytics/performance, which is computed
        live from entries.
      operationId: get-metrics-aggregation-summary
      parameters:
        - name: aggregationType
          in: path
          required: true
          schema:
            type: string
            enum:
              - HOURLY
              - DAILY
              - WEEKLY
              - MONTHLY
        - name: startTime
          in: query
          required: true
          schema:
            type: string
          description: Start time (ISO 8601, UTC).
        - name: endTime
          in: query
          required: true
          schema:
            type: string
          description: End time (ISO 8601, UTC).
      responses:
        200:
          description: Summary statistics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsAggregationSummary'
        400:
          $ref: '#/components/responses/InvalidRequest'
        403:
          $ref: '#/components/responses/AccessDenied'
        500:
          $ref: '#/components/responses/InternalServerError'
  /jans-fido2/restv1/metrics/analytics/adoption:
    get:
      tags:
        - FIDO2 Metrics
      summary: Get adoption analytics
      description: Returns user adoption metrics (new users, returning users, adoption rate).
      operationId: get-metrics-analytics-adoption
      parameters:
        - name: startTime
          in: query
          required: true
          schema:
            type: string
          description: Start time (ISO 8601, UTC).
        - name: endTime
          in: query
          required: true
          schema:
            type: string
          description: End time (ISO 8601, UTC).
      responses:
        200:
          description: Adoption analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsAdoption'
        400:
          $ref: '#/components/responses/InvalidRequest'
        403:
          $ref: '#/components/responses/AccessDenied'
        500:
          $ref: '#/components/responses/InternalServerError'
  /jans-fido2/restv1/metrics/analytics/performance:
    get:
      tags:
        - FIDO2 Metrics
      summary: Get performance analytics
      description: >-
        Returns performance statistics (average, min, max durations in milliseconds for registration
        and authentication). Durations cover only ceremonies that completed - SUCCESS or FAILURE.
        An abandoned ceremony's recorded duration is how long it stayed open before the sweep
        claimed it, which measures unfinishedRequestExpiration rather than user-perceived latency,
        so including it would make these figures track the configured window instead of the server.
        The keys for an operation type are absent when nothing completed in the range.
      operationId: get-metrics-analytics-performance
      parameters:
        - name: startTime
          in: query
          required: true
          schema:
            type: string
          description: Start time (ISO 8601, UTC).
        - name: endTime
          in: query
          required: true
          schema:
            type: string
          description: End time (ISO 8601, UTC).
      responses:
        200:
          description: Performance analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsPerformance'
        400:
          $ref: '#/components/responses/InvalidRequest'
        403:
          $ref: '#/components/responses/AccessDenied'
        500:
          $ref: '#/components/responses/InternalServerError'
  /jans-fido2/restv1/metrics/analytics/devices:
    get:
      tags:
        - FIDO2 Metrics
      summary: Get device analytics
      description: >-
        Returns device analytics (device types, OS, browsers, authenticator types). Counts are per
        completed ceremony, not per recorded entry: a ceremony writes an ATTEMPT when it starts and
        a terminal entry when it resolves, so counting entries reported one sign-in more than once.
        Abandoned ceremonies do not appear - abandonment is recorded off a request thread, which has
        no device details to read. Still approximate in multi-node deployments, where a ceremony can
        be recorded more than once.
      operationId: get-metrics-analytics-devices
      parameters:
        - name: startTime
          in: query
          required: true
          schema:
            type: string
          description: Start time (ISO 8601, UTC).
        - name: endTime
          in: query
          required: true
          schema:
            type: string
          description: End time (ISO 8601, UTC).
      responses:
        200:
          description: Device analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsDeviceAnalytics'
        400:
          $ref: '#/components/responses/InvalidRequest'
        403:
          $ref: '#/components/responses/AccessDenied'
        500:
          $ref: '#/components/responses/InternalServerError'
  /jans-fido2/restv1/metrics/analytics/errors:
    get:
      tags:
        - FIDO2 Metrics
      summary: Get error analytics
      description: >-
        Returns error analysis (categories, top errors, success/failure rates). Without
        operationType the tally covers registration and authentication together, which cannot
        distinguish a deployment with healthy sign-in and poor enrolment from the reverse - pass
        operationType to report one ceremony at a time.
      operationId: get-metrics-analytics-errors
      parameters:
        - name: startTime
          in: query
          required: true
          schema:
            type: string
          description: Start time (ISO 8601, UTC).
        - name: endTime
          in: query
          required: true
          schema:
            type: string
          description: End time (ISO 8601, UTC).
        - name: operationType
          in: query
          required: false
          schema:
            type: string
            enum: [REGISTRATION, AUTHENTICATION]
          description: >-
            Report this ceremony alone. Omit to report both together, which is the long-standing
            behaviour of this endpoint.
      responses:
        200:
          description: Error analytics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsErrorAnalytics'
        400:
          $ref: '#/components/responses/InvalidRequest'
        403:
          $ref: '#/components/responses/AccessDenied'
        500:
          $ref: '#/components/responses/InternalServerError'
  /jans-fido2/restv1/metrics/analytics/attestation-rejections:
    get:
      tags:
        - FIDO2 Metrics
      summary: Get attestation rejection analytics
      description: >-
        Returns attestation rejections broken down by trust diagnostic code. An unknown AAGUID, an
        authenticator blocked by an MDS status report and an untrusted root certificate are otherwise
        indistinguishable from each other, and from any other registration 

# --- truncated at 32 KB (62 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gluu/refs/heads/main/openapi/gluu-jans-fido2-openapi.yml