Skip to main content
Version: 11.3.0

Retrieving the Authenticator AAGUID

A successful FIDO2 authentication response returns the status and username, but not which authenticator model was used. Starting in HYPR Server 11.3.0, you can opt in to have the server include the credential's AAGUID (Authenticator Attestation GUID) in the assertion result.

The AAGUID identifies the authenticator make and model — for example, a YubiKey 5 series key, Windows Hello, or an iCloud Keychain passkey — and can be cross-referenced against the FIDO Alliance Metadata Service. Use it when you need to log or apply policy based on the authenticator used at sign-in.

Availability

Available in HYPR Server 11.3.0 and later, on the relying party FIDO2 API endpoint POST /rp/api/versioned/fido2/assertion/result.

The requestMeta Parameter​

The /assertion/result endpoint accepts an optional integer query parameter, requestMeta, that controls which metadata is added to the response. It is a bit-flag field:

ValueMeaning
0 (default)No metadata; the response is unchanged and fully backward compatible
1Include the credential's aaguid

Future metadata fields use additional bits (2, 4, and so on) and can be combined with a bitwise OR.

The rest of the FIDO2 authentication ceremony is unchanged: you still request options from /assertion/options, sign the challenge on the client, and post the assertion to /assertion/result. Only the result call takes the new parameter.

Request​

Add requestMeta=1 to the query string of the assertion result call. The request body is the standard ServerPublicKeyCredential assertion payload — unchanged:

{
  "id": "<credentialId>",
  "rawId": "<credentialId>",
  "response": {
    "authenticatorData": "<base64url>",
    "signature": "<base64url>",
    "clientDataJSON": "<base64url>"
  },
  "type": "public-key"
}

Example​

curl -X POST \
  "https://<your-server>/rp/api/versioned/fido2/assertion/result?requestMeta=1" \
  -H "Authorization: Bearer $API_TOKEN" \
  -H "Content-Type: application/json" \
  -d @assertion.json
Developer Tip

HYPR provides a Postman collection with samples of the REST APIs. You can see the public APIs that are currently available here.

Response​

On a successful authentication with requestMeta=1, the response includes a meta object:

{
  "status": "ok",
  "errorMessage": "",
  "username": "jdoe",
  "meta": {
    "aaguid": "01020304050607080102030405060708"
  }
}

The aaguid is the authenticator's AAGUID as a 32-character hexadecimal string, without dashes.

When the meta Object Is Omitted​

The response falls back to the standard payload, with no meta object, in these cases:

  • requestMeta is omitted or set to 0.

  • The authentication failed. Metadata is never attached to a failed result:

    {
      "status": "failed",
      "errorMessage": "Authentication failed"
    }

  • The credential has no AAGUID on record.

Because the field is opt-in and additive, existing integrations require no changes.

Software and Platform Authenticators

Many platform passkey providers report an all-zero AAGUID, or a provider-level AAGUID that identifies the passkey provider rather than a specific hardware model. Confirm what your authenticator population actually reports before enforcing policy based on the AAGUID.