openapi: 3.2.0
info:
  title: Gluu Fido2 - Trust API
  version: '1.0'
  description: 'Operations tagged Fido2 - Trust across 2 of this provider''s published API definitions: gluu-jans-config-api-fido2-plugin-openapi.yml, gluu-jans-fido2-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://jans.io/
  description: The Jans server
- url: https://jans.local.io
tags:
- name: Fido2 - Trust
paths:
  /fido2/trust/attestation/config:
    get:
      tags:
      - Fido2 - Trust
      summary: Get effective Fido2 attestation configuration
      description: Get effective Fido2 attestation configuration.
      operationId: get-fido2-trust-attestation-config
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonNode'
              examples:
                Response example:
                  description: Response example
                  value: "{\n    \"attestationMode\": \"monitor\",\n    \"attestationModeRecognized\": true,\n    \"unattestedAuthenticatorsAllowed\": true,\n    \"enterpriseAttestation\": false,\n    \"metadataServiceDisabled\": false,\n    \"appleRootCaPresent\": true,\n    \"enabledFidoAlgorithms\": [\n        \"RS256\",\n        \"ES256\"\n    ],\n    \"hints\": []\n}\n"
        '401':
          description: Unauthorized
        '500':
          description: InternalServerError
      security:
      - oauth2:
        - https://jans.io/oauth/config/fido2.readonly
      - oauth2:
        - https://jans.io/oauth/config/fido2.write
      - oauth2:
        - https://jans.io/oauth/config/fido2.admin
      - oauth2:
        - https://jans.io/oauth/config/read-all
    servers:
    - url: https://jans.io/
      description: The Jans server
  /fido2/trust/mds/health:
    get:
      tags:
      - Fido2 - Trust
      summary: Get Fido2 MDS health
      description: Get Fido2 MDS health.
      operationId: get-fido2-trust-mds-health
      responses:
        '200':
          description: Ok
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonNode'
              examples:
                Response example:
                  description: Response example
                  value: "{\n    \"status\": \"UP\",\n    \"metadataServiceDisabled\": false,\n    \"tocEntryCount\": 1284,\n    \"nextUpdate\": \"2026-08-15\",\n    \"blobExpired\": false,\n    \"lastSuccessfulRefresh\": \"2026-08-01T04:15:22Z\",\n    \"metadataServers\": [\n        {\n            \"url\": \"https://mds.fidoalliance.org/\",\n            \"rootCertConfigured\": false\n        }\n    ],\n    \"timestamp\": \"2026-08-07T09:31:04.118Z\"\n}\n"
        '401':
          description: Unauthorized
        '500':
          description: InternalServerError
        '503':
          description: Service Unavailable - the metadata service is DOWN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JsonNode'
      security:
      - oauth2:
        - https://jans.io/oauth/config/fido2.readonly
      - oauth2:
        - https://jans.io/oauth/config/fido2.write
      - oauth2:
        - https://jans.io/oauth/config/fido2.admin
      - oauth2:
        - https://jans.io/oauth/config/read-all
    servers:
    - url: https://jans.io/
      description: The Jans server
  /jans-fido2/restv1/trust/attestation/config:
    get:
      tags:
      - Fido2 - Trust
      summary: Get effective attestation configuration
      description: Returns the attestation policy the server is actually enforcing, so an administrator can see whether a strict mode is the reason authenticators are being rejected. Read-only.
      operationId: get-trust-attestation-config
      responses:
        200:
          description: Effective attestation configuration.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttestationTrustConfig'
        403:
          $ref: '#/components/responses/AccessDenied'
        500:
          $ref: '#/components/responses/InternalServerError'
    servers:
    - url: https://jans.local.io
  /jans-fido2/restv1/trust/mds/health:
    get:
      tags:
      - Fido2 - Trust
      summary: Get FIDO Metadata Service health
      description: 'Returns the state of the metadata used for attestation validation: how many entries are loaded, whether the loaded blob is still valid, and how the last refresh went. A stale or failed MDS load is a common cause of a previously valid authenticator suddenly being rejected. Read-only — this endpoint never triggers a metadata download or reads the document store.'
      operationId: get-trust-mds-health
      responses:
        200:
          description: MDS health. Returned for status UP and for status DISABLED — a metadata service switched off by configuration is a deliberate choice, not an outage, and must not page a monitor wired to this endpoint.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MdsHealth'
        503:
          description: Status is DOWN — no metadata is loaded, or the loaded blob has reached its nextUpdate (today or earlier) and a refresh is overdue. The diagnostic body is returned with the 503 as well.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MdsHealth'
        403:
          $ref: '#/components/responses/AccessDenied'
        500:
          $ref: '#/components/responses/InternalServerError'
    servers:
    - url: https://jans.local.io
components:
  schemas:
    JsonNode:
      type: object
    ErrorResponse:
      required:
      - error
      - error_description
      type: object
      properties:
        error:
          type: string
        error_description:
          type: string
        details:
          type: string
    MetadataServerStatus:
      type: object
      description: A configured MDS endpoint.
      properties:
        url:
          type: string
          example: https://mds.fidoalliance.org/
          description: The configured metadata endpoint URL.
        rootCertConfigured:
          type: boolean
          description: Whether a per-endpoint trust anchor (MetadataServer.rootCert) is configured. Reported as a presence flag only — the certificate itself never leaves the server.
    MdsHealth:
      type: object
      description: State of the FIDO Metadata Service data used for attestation validation. Read-only; assembled entirely from in-memory state.
      properties:
        status:
          type: string
          enum:
          - UP
          - DOWN
          - DISABLED
          description: 'UP — metadata is loaded and its nextUpdate is still in the future. DOWN — no entries are loaded, or the loaded blob has reached its nextUpdate (today or earlier) and a refresh is overdue; returned with HTTP 503. DISABLED — the metadata service is switched off by configuration; returned with HTTP 200, since that is a deliberate choice rather than an outage. Note that a failed refresh on its own is not DOWN: while the cached blob is still valid, attestation validation works normally. Alert on lastRefreshError for early warning that the metadata is heading towards expiry.'
        metadataServiceDisabled:
          type: boolean
          description: Whether MDS download and validation are switched off by configuration.
        tocEntryCount:
          type: integer
          example: 1284
          description: Authenticator metadata entries currently loaded in memory. Zero means attestation has no metadata to validate against.
        nextUpdate:
          type: string
          format: date
          example: '2026-08-15'
          description: The nextUpdate declared by the loaded TOC blob. Absent when no blob has been parsed since startup.
        blobExpired:
          type: boolean
          description: True when no blob is loaded, or its nextUpdate is today or earlier — i.e. a re-download is due. This is the same rule the server itself applies when deciding whether to download. Note that a blob is only discarded once its nextUpdate has actually passed, so on the day itself the blob is still in use while a refresh is already overdue.
        lastSuccessfulRefresh:
          type: string
          format: date-time
          example: '2026-08-01T04:15:22Z'
          description: When metadata was last downloaded and parsed successfully, as an ISO-8601 date-time with a UTC offset. Absent when no refresh has succeeded since startup.
        lastRefreshError:
          type: string
          example: 'MDS TOC download failed: Connection timed out'
          description: Why the most recent refresh failed; absent when the last refresh succeeded. Reports the first failure of the attempt, which is the root cause — a failed download is followed by a fallback to the cached blob that tends to fail too.
        metadataServers:
          type: array
          items:
            $ref: '#/components/schemas/MetadataServerStatus'
          description: The configured metadata endpoints.
        timestamp:
          type: string
          format: date-time
          example: '2026-08-07T09:31:04.118Z'
          description: When this health snapshot was taken, as an ISO-8601 date-time with a UTC offset.
    AttestationTrustConfig:
      type: object
      description: Effective attestation policy. Read-only view of the FIDO2 configuration; changing it is out of scope for this endpoint.
      properties:
        attestationMode:
          type: string
          example: monitor
          description: 'The configured attestation mode, reported verbatim (default "monitor"). The supported values are "disabled", "monitor" and "enforced", but this field is deliberately not constrained to them: an unsupported value is returned as-is rather than normalised, so a typo is visible — see attestationModeRecognized.'
        attestationModeRecognized:
          type: boolean
          description: Whether the configured value matches one of the supported modes. When false the server falls back to lenient behaviour, which is otherwise invisible to an administrator.
        unattestedAuthenticatorsAllowed:
          type: boolean
          description: Whether an authenticator that fails attestation validation is still accepted. True for every mode except "enforced" — only that mode applies the stricter MDS trust rules, so the default "monitor" still accepts such an authenticator.
        enterpriseAttestation:
          type: boolean
          description: Whether enterprise attestation is enabled.
        metadataServiceDisabled:
          type: boolean
          description: Whether MDS download and validation are switched off. When true, attestation cannot be validated against FIDO metadata.
        appleRootCaPresent:
          type: boolean
          description: Whether the Apple WebAuthn root CA certificate was loaded at startup. When false, Apple anonymous attestation cannot be validated.
        enabledFidoAlgorithms:
          type: array
          items:
            type: string
          example:
          - RS256
          - ES256
          description: Signature algorithms the server accepts.
        hints:
          type: array
          items:
            type: string
          example:
          - security-key
          - client-device
          - hybrid
          description: Configured RP hints.
  responses:
    InternalServerError:
      description: Internal error occured. Please check log file for details.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    AccessDenied:
      description: Invalid details provided hence access denied.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://{op-hostname}/.../token
          scopes:
            https://jans.io/oauth/config/fido2.readonly: View fido2 config related information
            https://jans.io/oauth/config/fido2.write: Manage fido2 config related information
            https://jans.io/oauth/config/fido2.delete: Delete fido2 config related information
            https://jans.io/oauth/config/fido2-metrics.readonly: View fido2 metrics related information
            https://jans.io/oauth/config/fido2.admin: Admin to manage fido2 related information
            https://jans.io/oauth/config/read-all: Super admin for viewing application resource information
            https://jans.io/oauth/config/write-all: Super admin for updating application resource information
            https://jans.io/oauth/config/delete-all: Super admin for deleting application resource information
x-refined-from:
- gluu-jans-config-api-fido2-plugin-openapi.yml
- gluu-jans-fido2-openapi.yml