Skip to main content
Version: 10.5.0

FIDO2 Authenticators Granular Control

Prerequisites

Before using the FIDO2 Authenticators Granular Control API, ensure that FIDO2 Settings are properly configured for your application.

FIDO2 Authenticators Granular Control allows administrators to manage which authenticators are allowed for use with your applications through the HYPR API. This includes managing authenticator policies and enabling or disabling specific authenticator types based on their Authenticator Attestation Global Unique Identifier (AAGUID).

API Endpoints​

The FIDO2 Authenticators Granular Control API provides the following endpoints for managing authenticator policies:

List All Enabled Authenticators​

GET /rp/api/fido2/authenticators/isenabled
Authorization: Bearer <access_token>

Response:

{
  "success": true,
  "message": "",
  "response": [
    {
      "aaguid": "12345678-1234-1234-1234-123456789012",
      "allowed": true,
      "friendlyName": "Example Authenticator"
    }
  ]
}

Modify Authenticator Policies​

This endpoint allows you to enable or disable authenticators for a specific RP App. You can only have either an allowlist (allowed=true) or denylist (allowed=false) policy at a time.

POST /rp/api/fido2/authenticators/modify
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "rpAppId": "your-rp-app-id",
  "aaguids": [
    "12345678-1234-1234-1234-123456789012",
    "87654321-4321-4321-4321-210987654321"
  ],
  "allowed": true
}

Response:

{
  "success": true,
  "message": "Added to allowlist",
  "response": [
    {
      "aaguid": "12345678-1234-1234-1234-123456789012",
      "allowed": true,
      "friendlyName": "Example Authenticator"
    }
  ]
}

Remove Authenticator Policies​

This endpoint allows you to remove specific authenticators from the current policy.

POST /rp/api/fido2/authenticators/remove
Authorization: Bearer <access_token>
Content-Type: application/json

{
  "rpAppId": "your-rp-app-id",
  "aaguids": [
    "12345678-1234-1234-1234-123456789012"
  ]
}

Response:

{
  "success": true,
  "message": "Removed authenticators from policy",
  "response": [
    {
      "aaguid": "87654321-4321-4321-4321-210987654321",
      "allowed": true,
      "friendlyName": "Example Authenticator"
    }
  ]
}
Deprecated Endpoints

The following endpoints are deprecated and will be removed in version 11.3. Use the /modify endpoint instead:

  • POST /rp/api/fido2/authenticators/enable
  • POST /rp/api/fido2/authenticators/disable

Best Practices​

  • Regularly review enabled authenticators to ensure only approved devices are allowed
  • Document any changes to authenticator policies
  • Test authenticator changes in a staging environment before applying to production
  • Keep a record of AAGUIDs for commonly used authenticators
  • Implement proper error handling for API responses
  • Use the /modify endpoint instead of separate enable/disable endpoints
  • Maintain either an allowlist or denylist policy, but not both simultaneously

Error Handling​

The API may return the following error codes:

Error CodeDescriptionAction
401UnauthorizedCheck your access token and permissions
403ForbiddenVerify you have the required scopes
400Bad RequestValidate your request payload
500Internal Server ErrorContact HYPR Support

Common error scenarios:

  • Attempting to add to an allowlist while a denylist exists
  • Attempting to add to a denylist while an allowlist exists
  • Invalid AAGUID format
  • Missing required permissions