Policy management

This section explains how to manage authenticator policies using the authenticator policy admin API.

The authenticator policy admin API provides operations for configuring policies that control which types of authenticators can be used for registration and authentication.

The authenticator policy admin API allows you to:

Create policies: Defines a new policy with authenticator requirements and behavior rules.
List policies: Retrieves all policies for a tenant, with optional filtering by name.
Get policy: Retrieves a specific policy by its identifier.
Update policy: Modifies an existing policy's fields.
Delete policy: Removes a policy from the tenant.
Get policy history: Retrieves the change history for a specific policy.

Policy fields reference

The following table summarizes all configurable policy fields:

Field	Description
`name`	Unique policy name (mandatory on creation).
`discoverable`	Whether discoverable (resident) credentials are `required`, `preferred`, or `discouraged`.
`userVerification`	User verification requirement: `required`, `preferred`, or `discouraged`.
`backupEligible`	Whether synchronized passkeys are allowed (`true`), disallowed (`false`), or unrestricted (omit).
`deviceType`	List of allowed device types (e.g., `platform`, `cross-platform`, `security-key`, `device-binding`).
`metadata`	FIDO certification level requirement: `no`, `listed`, `certified`, `certified-1`, `certified-2`, `certified-3`.
`algorithm`	List of allowed COSE algorithm identifiers (e.g., `-7` for ES256).
`whitelist`	List of AAGUIDs or attestation certificate key identifiers to explicitly allow.
`blacklist`	List of AAGUIDs or attestation certificate key identifiers to explicitly deny.
`outcome`	Policy failure outcome: `fail` (block operation) or `warn` (allow with warning).
`maxDbkPerAuthenticator`	Maximum number of device-bound keys per authenticator (default: `5`).
`authenticatorLockout`	Lockout configuration with `maxFailures`, `windowSeconds`, and `blockSeconds`.

Policy lifecycle

Creating a policy

Creates a policy using the create authenticator policy operation. The name field is mandatory and must be unique within the tenant.

POST /policies
{
    "name": "MyPolicy",
    "userVerification": "required",
    "discoverable": "preferred",
    "metadata": "no"
}

Retrieving policies

Retrieve all policies for a tenant using the list authenticator policies operation. You can filter by name using the optional name query parameter:

GET /policies?name=MyPolicy

Retrieve a specific policy by its policyId using the get authenticator policy operation:

GET /policies/{policyId}

Updating a policy

Update an existing policy using the update authenticator policy operation. Only the fields included in the request body are updated; all other fields remain unchanged.

PATCH /policies/{policyId}
{
    "userVerification": "required"
}

Deleting a policy

Delete a policy using the delete authenticator policy operation:

DELETE /policies/{policyId}

Note

Deleting a policy also removes its change history from the FIDO server.

Policy change history

Each policy change is recorded. Retrieve the history of changes for a specific policy using the get policy history operation:

GET /policies/{policyId}/history

Authentication and authorization

All authenticator policy admin API operations require proper authentication:

Operations require specific roles encoded in the JWT token passed as an HTTP Authorization request header with the Bearer authorization scheme.
Each operation specifies the required role in its API documentation.

Next steps

Review the authenticator policy admin API reference for detailed endpoint documentation.
Read the authenticator policy overview for guidance on using policies in FIDO operations.
Explore authenticator policy samples for example configurations.
Learn about authenticator management.
Review user management.

Suggest A Change