FIDO2 MDS Server (API)

Prerequisites

Before using the FIDO2 MDS Server API, ensure that FIDO2 is enabled on your HYPR deployment.

The FIDO2 MDS Server API provides programmatic access to the authenticator metadata catalog. Use these endpoints to query metadata by AAGUID, search with filters, discover available filter options, and manage custom metadata entries.

API Endpoints

All endpoints are versioned under /rp/api/versioned/fido2/mds.

Introspect Available Filters

Returns the available search filters and their possible values, dynamically discovered from the current metadata catalog. Use this endpoint to build dynamic UIs or validate filter inputs before querying.

GET /rp/api/versioned/fido2/mds/introspect
Authorization: Bearer <access_token>

Required Scope: RP_REPORT

Response:

{
  "filters": [
    {
      "name": "q",
      "type": "string",
      "description": "Free text search against AAGUID and description",
      "examples": ["YubiKey 5 Series", "Windows Hello"]
    },
    {
      "name": "enabled",
      "type": "boolean",
      "description": "Filter by enabled/disabled status",
      "examples": ["true", "false"]
    },
    {
      "name": "status",
      "type": "string",
      "description": "Filter by FIDO certification status",
      "examples": ["FIDO_CERTIFIED", "FIDO_CERTIFIED_L1", "FIDO_CERTIFIED_L2", "NOT_FIDO_CERTIFIED"]
    },
    {
      "name": "uvm",
      "type": "array<string>",
      "description": "Filter by user verification methods (OR match)",
      "examples": ["fingerprint_internal", "presence_internal", "passcode_internal"]
    },
    {
      "name": "transports",
      "type": "array<string>",
      "description": "Filter by supported transport protocols (OR match)",
      "examples": ["usb", "nfc", "ble", "internal", "hybrid"]
    },
    {
      "name": "attachment",
      "type": "array<string>",
      "description": "Filter by authenticator attachment type (OR match)",
      "examples": ["internal", "external", "wired", "wireless"]
    },
    {
      "name": "keyProtection",
      "type": "array<string>",
      "description": "Filter by key protection mechanism (OR match)",
      "examples": ["hardware", "software", "tee", "secure_element"]
    },
    {
      "name": "algorithms",
      "type": "array<string>",
      "description": "Filter by supported cryptographic algorithms (OR match)",
      "examples": ["secp256r1_ecdsa_sha256_raw", "ed25519_eddsa_sha512_raw"]
    }
  ]
}

tip

The examples values are dynamically discovered from the actual metadata in your deployment. They reflect what's currently available, not a static list.

Query by AAGUID

Retrieve the metadata statement for a specific authenticator by its AAGUID. Supports field projection to return only the fields you need.

POST /rp/api/versioned/fido2/mds/query
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "aaguid": "12345678-1234-1234-1234-123456789012",
  "fields": ["description", "protocolFamily", "authenticatorVersion", "upv"]
}

Required Scope: RP_REPORT

Parameters:

Field	Type	Required	Description
aaguid	string	Yes	AAGUID of the authenticator (UUID format)
fields	array<string>	No	List of MetadataStatement fields to return. If omitted, all fields are returned.

Response:

{
  "aaguid": "12345678-1234-1234-1234-123456789012",
  "fields": {
    "description": "Example Authenticator",
    "protocolFamily": "fido2",
    "authenticatorVersion": 5,
    "upv": [{ "major": 1, "minor": 0 }]
  }
}

Search Metadata

Search across all metadata entries using filters with optional field projection and pagination.

POST /rp/api/versioned/fido2/mds/query/search
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "q": "YubiKey",
  "status": "FIDO_CERTIFIED",
  "transports": ["usb", "nfc"],
  "fields": ["description", "aaguid", "statusReports"],
  "page": 0,
  "pageSize": 20
}

Required Scope: RP_REPORT

Parameters:

Field	Type	Required	Description
q	string	No	Free text search against AAGUID and description
enabled	boolean	No	Filter by enabled/disabled status
status	string	No	FIDO certification status
uvm	array<string>	No	User verification methods (OR match)
transports	array<string>	No	Transport protocols (OR match)
attachment	array<string>	No	Attachment types (OR match)
keyProtection	array<string>	No	Key protection mechanisms (OR match)
algorithms	array<string>	No	Cryptographic algorithms (OR match)
fields	array<string>	No	MetadataStatement fields to return. If omitted, all fields are returned.
page	integer	No	Page number (0-based, default 0)
pageSize	integer	No	Results per page (default 20)

Response:

{
  "content": [
    {
      "aaguid": "12345678-1234-1234-1234-123456789012",
      "fields": {
        "description": "YubiKey 5 Series",
        "aaguid": "12345678-1234-1234-1234-123456789012",
        "statusReports": [{ "status": "FIDO_CERTIFIED", "effectiveDate": "2024-01-15" }]
      }
    }
  ],
  "page": 0,
  "pageSize": 20,
  "totalElements": 1,
  "totalPages": 1
}

Upload Metadata Statement

Upload a custom FIDO2 metadata statement for an authenticator not covered by the FIDO Alliance MDS.

PUT /rp/api/versioned/fido2/mds
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "aaguid": "12345678-1234-1234-1234-123456789012",
  "description": "Custom Authenticator",
  "protocolFamily": "fido2",
  ...
}

Required Scope: CC admin token

Request Body: A valid FIDO2 MetadataStatement JSON object.

Response: 204 No Content

List All Metadata Entries

Retrieve all metadata entries in the catalog.

GET /rp/api/versioned/fido2/mds
Authorization: Bearer <access_token>

Required Scope: CC admin token

Response:

[
  {
    "aaguid": "12345678-1234-1234-1234-123456789012",
    "description": "Example Authenticator",
    "enabled": true,
    "source": "METADATA_SERVICE"
  }
]

Delete Metadata Entry

Delete a metadata entry by AAGUID.

DELETE /rp/api/versioned/fido2/mds/{aaguid}
Authorization: Bearer <access_token>

Required Scope: CC admin token

Response: 204 No Content

caution

Unlike the UI, the API does not restrict deletion to manually uploaded entries. Deleting an MDS-sourced entry will cause it to reappear on the next MDS sync cycle.

Error Handling

Error Code	Description	Action
400	Bad Request	Validate request payload and AAGUID format
401	Unauthorized	Check your access token
403	Forbidden	Verify required scopes
404	Not Found	AAGUID does not exist in the catalog
429	Too Many Requests	Upload endpoint is rate-limited (10 requests per 60 seconds per user)
500	Internal Server Error	Contact HYPR Support

Related Information

• FIDO2 MDS Server (UI) - Browse metadata through the Control Center interface
• FIDO2 Authenticators Granular Control (API) - Per-application AAGUID policy management
• FIDO2 Settings - Per-application FIDO2 configuration