---
title: "Nok Nok data types"
slug: "s3suite94-nok-nok-data-types"
updated: 2026-10-27T18:42:16Z
published: 2026-10-27T18:42:16Z
canonical: "docs.onespan.com/s3suite94-nok-nok-data-types"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onespan.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Nok Nok data types

The API Server REST API operations return information in data structures that use a JSON format. There are distinct data structures that correspond to concepts like apps, authenticators, authentication methods, devices, sequences, and information about the Adaptive Rule that succeeded.

## AdaptiveRuleSetResult

AdaptiveRuleSetResult contains information about the succeeding Adaptive Rule after a user has either registered or been authenticated. This structure is used to return information to the App SDK in the response.

> The fields listed in the table are indicative but not exhaustive. The Server may return additional fields.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| action | String | The action to be taken. For a Registration Decision Rule, one of: - SUGGEST_REGISTRATION - ENFORCE_REGISTRATION - DENY - IGNORE_REGISTRATION For an Authentication Rule, one of: - TRIGGER_AUTHENTICATION - ALLOW - DENY Always returned. |
| authSequenceId | String | ID of the authentication sequence. For authentication, App SDK uses the methods in this sequence to authenticate the user. For registration, the sequence contains the authentication methods that the user should register. Returned in the response when the action is TRIGGER_AUTHENTICATION and authentication is finished. |
| maxTimeAllowedInSeconds | Integer | Applies only to an Authentication Rule. Maximum time in seconds for the user to complete any of the authentication sequences, each of which may contain one or more authentication methods. A user specifies this information when they define an Authentication Rule. Your app can use this to tell a user how much time they have to complete authentication or warn the user that the Server does not accept a response beyond maxTimeAllowedInSeconds. |
| riskScore | Integer | Applies only to an Authentication Rule. The risk score associated with the authentication sequence. Returned in the response when the action is TRIGGER_AUTHENTICATION and if the authentication sequence has a risk score. |
| ruleName | String | The name of the Adaptive Rule whose condition evaluated to true based on the incoming signals, incoming context data, and user data from the database. Always returned. |
| ruleSetName | String | The name of the Adaptive Ruleset that was chosen for the client app requesting registration or authentication. Always returned. |

## AdditionalErrorInfo

The API Server returns additionalErrorInfo in the response if there is more information available from one of its plugins. Currently, this is used by the JWT External Authentication plugin and that plugin uses the following structure.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| outcome | String | Reason for the error. |

For example, when credential validation for a Nok Nok JWTAuthenticationPlugin external authentication method fails:

```plaintext
{
    "additionalErrorInfo":{
        "outcome":"ExternalAuthFailed"
    }
}
```

If you create a custom API Server plugin, you can implement it to provide additional error information using this structure. Because additionalErrorInfo is a JSON object, your custom plugin can add custom fields and omit the outcome field. For more information, refer to the PluginException class, which is additionalErrorInfo's base class, in the API Server's Java docs.

## AdditionalInfo

The API Server returns additionalInfo in the response provided that:

- The value of the optionsData.needDetails field in the request is 2 or 3.
- You configured the API Server's response filter to return data.

By default, the API Server returns all device-related information, the IDs of the authenticators used in the REST operation, and attachment hints for FIDO2 authenticators. You can configure the API Server to return more or less data by modifying its response filter configuration. Refer to [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration).

Depending on the API operation and attributes in the request, the additionalInfo field can contain [RulesResult](/dpoa/docs/s3suite94-nok-nok-data-types#rulesresult), [AuthenticatorResult](/dpoa/docs/s3suite94-nok-nok-data-types#authenticatorresult), [DeviceDetail](/dpoa/docs/s3suite94-nok-nok-data-types#devicedetail), [Extension](/dpoa/docs/s3suite94-nok-nok-data-types#extension), and other entries. The additionalInfo attributes listed in the table below are indicative but not exhaustive.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| app | [App](/dpoa/docs/s3suite94-nok-nok-data-types#app) | Information about the calling client app |
| appID | String | The calling client app's UAF application ID. Returned if the operation is LIST_REG and optionsData.needDetails is 3. |
| authenticatorsResults | List<[AuthenticatorResult](/dpoa/docs/s3suite94-nok-nok-data-types#authenticatorresult)> | List of the authenticators that succeeded or failed to complete authentication. This info is specific to the protocol. |
| authNotificationText | String | Dynamic push notification text if sent during INIT_VERIFY and the push was successful then the same will be emitted back when authentication succeeds. Applies only to the FIDO OOB Auth method. |
| device | [DeviceDetail](/dpoa/docs/s3suite94-nok-nok-data-types#devicedetail) | Device details received from the client provided that the Server received this information in the request via message. |
| elapsedTime | Integer | The amount of time, in milliseconds, to process the request for a REST API Operation. |
| extensions | List<[Extension](/dpoa/docs/s3suite94-nok-nok-data-types#extension)> | Message payload extensions received by the Server. |
| headerExtensions | List<[HeaderExtension](/dpoa/docs/s3suite94-nok-nok-data-types#headerextension)> | Protocol-specific header extensions. |
| oobRefID | String | ID provided by the RP app to retrieve contextual information from the RP server that can be displayed to the app user. Only returned by an OOB REST API operation if oobRefId was included inside oobData in the scanned QR code or push notification. 512 character maximum. |
| protocol | String | Protocol used by the Authentication Server based on information from the request. If this is missing from the request, the Server uses the UAF protocol. |
| protocolFamily | String | protocolFamily is uaf or web. Returned if: i) the operation is LIST_REG, and ii) optionsData.needDetails is 2 or 3, and iii) the response filter is configured to return it. |
| policyName | String | FIDO Policy name used to verify the authenticator for the operation. |
| rpID | String | The calling client app's FIDO2 RP ID. Returned if the operation is LIST_REG and optionsData.needDetails is 3. |
| rulesResult | [RulesResult](/dpoa/docs/s3suite94-nok-nok-data-types#rulesresult) | Results from all matching FIDO policy risk rules. |
| transaction | Transaction object | This object has one attribute: id. |

## App

App is a data structure containing information about each application installed on the device. It has the following attributes:

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| displayName | String | A user-friendly name for the app. |
| id | String | The unique identifier for the app that is generated by the Nok Nok App SDK. |
| name | String | The name of the app. |
| qrSupported | Boolean | If true, the app can perform FIDO OOB authentication on the 2nd device because the device it's running on can scan a QR code and authenticate the user. For example, mobile devices are capable of scanning a QR code, while desktop systems and laptops typically cannot. The App SDK knows if the app has implemented FIDO OOB support and can determine if the device can scan a QR code. It includes that information in the message attribute in the request to the Auth Server. While performing Adaptive Registration and Adaptive Authentication, the Server uses this data along with the app's push-notification configuration to dictate if the user can register or authenticate with FIDO OOB. However, if the app is configured not to support QR code scanning in the Server Admin Console, this overrides what the App SDK sends. The value is returned in case the calling app needs to reference it. |

For example:

```plaintext
"app":  {
    "displayName":"NokNok Example App",
    "id":"android:apk-key-hash:rDQ4Tn60fAvxP8thtp6sOh5ococ",
    "name":"android:com.example.noknok.app",
    "qrSupported": true
}
```

## AppAttest

AppAttest is a data structure that represents information about an Apple app’s attestation, to verify the integrity of the app. It is technically an authenticator extension and can be present for both UAF and FIDO2 authenticators on an Apple platform. Use the App Attest service to provide assurance that clients connecting to your server are valid instances of your app. AppAttest asserts that the authenticator has attestation and the app is legitimate. For more information, see [https://developer.apple.com/documentation/devicecheck/establishing_your_app_s_integrity](https://developer.apple.com/documentation/devicecheck/establishing_your_app_s_integrity).

This data structure is based on the Nok Nok-proprietary extension, noknok.appattest, which processes App Attest as per Apple’s developer specification, refer to above link. AppAttest is optionally returned in the response of REST API operations. Refer to the list at the end of this section.

> The fields listed in the following table are indicative, but not exhaustive. The Server may return additional fields.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| aaguid | String | The FIDO2 Authenticator Attestation GUID. One of the 2 AAGUIDs listed below: - appattestdevelop[61707061-7474-6573-7464-6576656c6f70] - appattest0000000[61707061-7474-6573-7400-000000000000] |
| attestationFormat | String | The string "apple-appattest". |
| attachmentHints | Array of strings | Only one string value is listed in the array, it is always “internal”. |
| authenticatorVersion | Integer | The authenticator version. |
| backedUp | Boolean | Always False. |
| backUpEligible | Boolean | Always False. |
| handle | String | Unique identifier for the AppAttest authenticator. |
| state | String | The outcome after the Auth Server processes the noknok.appattest extension. - NOT_APPLICABLE: The AppAttest extension is not applicable. For example, the information may pertain to an Android platform. - UNAVAILABLE_ON_CLIENT: The AppAttest extension was not sent in the request. - UNAVAILABLE_ON_SERVER: The AppAttest information is not present on the Auth Server’s database. - INVALID: The AppAttest extension is invalid. - UNTRUSTED: The device is not trusted, additional authentication may be necessary. The user is authenticating with a synced passkey that has not been used on the current device. - TRUSTED: The device is trusted. The user either registered the synced passkey on the current device or previously authenticated successfully with the passkey on the current device. - SUSPENDED: The AppAttest is suspended |
| userPresence | Boolean | Always False. |
| userVerification | Boolean | Always False. |

The following REST API operations can return AppAttest as a part of the response payload.

- [FINISH_REG](/dpoa/docs/s3suite94-fido-registration#finishreg)
- [FINISH_OOB_REG](/dpoa/docs/s3suite94-out-of-band-registration#finishoobreg)
- [STATUS_OOB_REG](/dpoa/docs/s3suite94-out-of-band-registration#statusoobreg)
- [FINISH_OOB_AUTH](/dpoa/docs/s3suite94-out-of-band-authentication#finishoobauth)
- [STATUS_OOB_AUTH](/dpoa/docs/s3suite94-out-of-band-authentication#statusoobauth)
- [VERIFY](/dpoa/docs/s3suite94-reference-restapi-fido-authentication#verify)

## Authentication Method

Method contains information about authentication methods used in Adaptive Registration and Adaptive Authentication. Authentication methods include FIDO auth, FIDO OOB, Email OTP, SMS OTP, and Photo ID. Method can be present in the request as well as response in Adaptive REST API interactions.

> The fields listed in the table are indicative but not exhaustive. The Server may return additional fields.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| data | JsonElement | Contains information specific to the authentication method. For example, for SMS OTP, this would be the user's cell phone. The fields in this object can vary depending on the type of authentication method, the REST API operation, and whether the object is in an operation's request or response. For details, refer to the specific type of authentication method: - [FIDO Auth](/dpoa/docs/s3suite94-nok-nok-data-types#fido-auth) - [FIDO OOB Auth](/dpoa/docs/s3suite94-nok-nok-data-types#fido-oob-auth) - [Email OTP](/dpoa/docs/s3suite94-nok-nok-data-types#email-otp) - [External Authentication](/dpoa/docs/s3suite94-nok-nok-data-types#external-authentication) - [Photo ID](/dpoa/docs/s3suite94-nok-nok-data-types#photo-id) - [SMS OTP](/dpoa/docs/s3suite94-nok-nok-data-types#sms-otp) |
| errorCode | String | Server-specific error code available when method processing has failed. Can be present in the response. For “FIDO Auth” this can be the status code for failures. |
| lifetimeMillis | Long | Lifetime to complete method setup or verification in milliseconds. Can be present in the response. Your client or web app can use this to tell a user how much time they have to complete the task or warn the user that the Server does not accept a response once lifetimeMillis has expired. |
| name | String | Name of the authentication method that the Server is registering for a particular tenant. Required. Present in both the request and response. For example, recovery, bootstrap, etc. |
| state | String | State of the authentication method. Can be conditionally present in the response. - AWAITING_USER_ACTION - CANCELLED - IN_PROGRESS - PENDING - SUCCEEDED |
| statusHandle | String | Present in the response from INIT_ADAPTIVE, INIT_VERIFY or INIT_SETUP. Present in both the requests to and responses from SETUP, VERIFY, CANCEL_SETUP, and CANCEL_VERIFY. |
| type | String | Identifies the authentication method. Required. One of: - FIDO Auth - FIDO OOB Auth - Email OTP - SMS OTP - Photo ID - External Auth |

### Data Field Contents by Authentication Method

The contents of the data field depend on the authentication method. The tables below describe what the expected structure is. For FIDO OOB Auth and FIDO Auth, there are separate tables that describe the structure based on whether the information is sent in a request or response to/from INIT_ADAPTIVE, INIT_VERIFY, and/or VERIFY.

#### FIDO Auth

In the response for [INIT_ADAPTIVE](/dpoa/docs/s3suite94-rest-api), the method.data field for FIDO Auth contains the fields below.

| **Field** | **Description** |
| --- | --- |
| additionalInfo | An object containing information from the client app that is initiating authentication. In order for the API Server to return this information: 1. The client app must have sent this information in the INIT_ADAPTIVE request message attribute. 2. You configured the API Server's response filter to return the protocol. Refer to [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration). |
| protocol | Protocol used by the Server based on information from the request. String. One of UAF or Web. |
| message | Opaque value that contains the challenge exchanged between the Server and the App SDK. A base64-URL encoded string. message must be sent to the App SDK. |
| statusCode | One of 3 codes that report the success of the requested operation. See Success Status Codes below for possible values. |

##### Success Status Codes

| **Success Status Code** | **Description** | **Examples** |
| --- | --- | --- |
| 4000 | OK. Operation completed | Authentication completed successfully. |
| 4001 | OK. Credential variance | UVI is different uaf.exact.match=true |
| 4002 | OK. Optional security checks failed. | Failed to validate ChannelBinding. |

In the request for [VERIFY](/dpoa/docs/s3suite94-reference-restapi-fido-authentication#verify), the method.data field for FIDO Auth contains the field below.

| **Field** | **Description** |
| --- | --- |
| channelBinding | Optional. Channel binding data available from the TLS endpoint. [ChannelBinding](/dpoa/docs/s3suite94-nok-nok-data-types#channelbinding). |
| message | Required. Generated by the App SDK on the client. An opaque value. The client app is responsible for sending message. A base64-URL encoded string. |

In the response from [VERIFY](/dpoa/docs/s3suite94-reference-restapi-fido-authentication#verify), when successful, the method.data field for FIDO Auth contains the fields below.

| **Field** | **Description** |
| --- | --- |
| additionalInfo | An object containing information from the client app that is initiating authentication. In order for the API Server to return this information: 1. The client app must have sent this information in the INIT_ADAPTIVE request message attribute. 2. You configured the API Server's response filter to return the protocol, policy name, transaction ID, additional authenticator details, risk rule results, and extension information. By default, the API Server returns all device-related information, the IDs of the authenticators used, and attachment hints for FIDO2 authenticators. Refer to [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration). |
| additionalInfo.protocol | Protocol used by the Server. String. One of UAF or Web. |
| additionalInfo.policyName | FIDO policy name used for VERIFY. String. |
| additionalInfo.transaction:id | Transaction ID provided by the client app to track a transaction. String. The transaction ID is provided in the request payload of [INIT_ADAPTIVE](/dpoa/docs/s3suite94-rest-api). |
| additionalInfo.authenticatorsResult | List of the authenticators that succeeded or failed to complete authentication. List<[AuthenticatorResult](/dpoa/docs/s3suite94-nok-nok-data-types#authenticatorresult)>. |
| additionalInfo.authenticatorsResult.transactionResult | If VERIFY performs a transaction, AuthenticatorResult also includes [TransactionResult](/dpoa/docs/s3suite94-nok-nok-data-types#transactionresult). |
| additionalInfo.rulesResult | RulesResult populated as a result of policy rules processing giving out the matched rules details. [RulesResult](/dpoa/docs/s3suite94-nok-nok-data-types#rulesresult). |
| additionalInfo.headerExtensions | Protocol-specific header extensions. List<[HeaderExtension](/dpoa/docs/s3suite94-nok-nok-data-types#headerextension)> |
| additionalInfo.extensions | Message payload extensions received by the Server in the [INIT_ADAPTIVE](/dpoa/docs/s3suite94-rest-api) and [VERIFY](/dpoa/docs/s3suite94-reference-restapi-fido-authentication#verify) request. List<[Extension](/dpoa/docs/s3suite94-nok-nok-data-types#extension)> |
| additionalInfo.elapsedTime | Time elapsed while processing the request |
| message | Information exchanged between the Server and the App SDK. message must be sent to the App SDK and is accepted conditionally. Base64-URL encoded string. |
| statusCode | One of 3 codes that report the success of the requested operation. See Success Status Codes above for possible values. |

In the response for [INIT_ADAPTIVE_REG](/dpoa/docs/s3suite94-adaptive-registration#initadaptivereg), the method.data field for FIDO Auth can optionally contain the field below.

| **Field** | **Description** |
| --- | --- |
| message | Opaque value that contains the challenge exchanged between the Server and the App SDK. A base64-URL encoded string. message must be sent to the App SDK. |

#### FIDO OOB Auth

In the response from [INIT_ADAPTIVE](/dpoa/docs/s3suite94-rest-api) when the operation is successful.

| **Field** | **Description** |
| --- | --- |
| devices | Optionally present if userName is sent in the INIT_ADAPTIVE request. A set of DeviceEntry objects. A DeviceEntry object contains device, app, and pushHandle. - device: A Nok Nok data structure containing device information. - app: A Nok Nok data structure containing information about the applications installed on the device. - pushHandle: Identifies the device that receives a push notification and then initiates an OOB authentication. A Base64-encoded string, maximum 4000 characters. |

Present in an [INIT_VERIFY request](/dpoa/docs/s3suite94-rest-api), the method.data field for FIDO OOB Auth contains the fields below.

| **Field** | **Description** |
| --- | --- |
| authNotificationText | Optional. Dynamic push notification text sent in the push payload to the second device during OOB. Requires that you assign the value dynamic to oob.auth.notification.text.mode, a tenant property. For instructions on how to set this property, refer to oob.auth.notification.text.mode in [*4.d. Optional: Configure to Use Dynamic Authentication Text*](/dpoa/docs/s3suite94-step-4-configure-the-servers-for-push-notifications#4d-optional-configure-dynamic-authentication-text). |
| oobMode | Required. Object with 3 attributes, qr, push, and rawdata. Specifies the OOB mechanism to use in order to authenticate on the second device. You must provide at least one of oobMode.qr, oobMode.push, or oobMode.rawData. |
| oobMode.push | Optional. String. Enter true or false as follows: - true: The Server generates and sends a push notification. One of the following entries must be provided for push notification: - userName - Send a push to any of the user’s most recently used device: - A device on which the last push notification was successful. - A device that was recently updated and also has a corresponding push notification identifier. - pushHandle - false: The Server does not send a push notification. |
| oobMode.qr | Optional. String. Enter true or false as follows: - true: The Server generates a QR code image for initiating the OOB operation. - false: The Server does not generate a QR code image. |
| oobMode.qrType | Optional. String. Directs the Auth Server to generate the specified QR code. One of the values listed below, these are ordered by the size of the QR code they generate, from largest to smallest. - UNIVERSAL_ANY_RP: Generates a universal QR Code that can be scanned by web apps, native mobile apps, and camera apps capable of processing a QR code. These apps can be deployed by different organizations. - UNIVERSAL_RP_SPECIFIC: Generates a universal QR Code specific to apps deployed by one organization. The Server omits the API Server hostname from the QR code. - APP_ANY_RP (default): Generates a QR Code that works with native mobile apps deployed by different organizations. The Server omits the web page hostname from the QR code. - APP_RP_SPECIFIC: Generates a QR code that can only be scanned by native mobile apps deployed by one organization. The Server omits both the web page and API Server hostname from the QR code. Mobile apps that scan this QR code must hard code the registration and authentication endpoints as described in the [Android Developer Guide](/dpoa/docs/s3suite94-android-developer-guide-for-android) or the [iOS Developer Guide](/dpoa/docs/s3suite94-implementing-authentication-in-your-app#initializing-the-oob-sdk). |
| oobMode.rawData | Optional. String. Enter true or false as follows: - false: You are using QR code or push notification, so you don’t need raw data. - true: You are using your own mechanism to transfer information from the initiating device to a second device, so you need raw data to encode that information. |
| oobMode.webUrl | Required if oobMode.qrType is either UNIVERSAL_RP_SPECIFIC or UNIVERSAL_ANY_RP. The web page URL that handles OOB authentication. The Server encodes this web page URL in the generated QR code. String. |
| oobRefId | Optional. An alphanumeric string, maximum of 512 characters. ID provided by the RP app to retrieve contextual information from the RP server that can be displayed to the app user. This helps maintain continuity when a user is performing a transaction or task. The system takes the oobRefId and packages it inside oobData. oobData is incorporated in the displayed QR code or sent via a push notification. The app running on the second device accesses oobRefID after it scans the QR code or receives the push notification. |

In the [response from INIT_VERIFY](/dpoa/docs/s3suite94-non-fido-authentication#response) when the operation is successful, the method.data field for FIDO OOB Auth contains the fields below.

| **Field** | **Description** |
| --- | --- |
| additionalInfo | An object containing information returned by the Server. In order for the API Server to return this information, 1. Send oobRefID in the method.data field of INIT_VERIFY's request. 2. Update the response filter configuration so the API Server returns this attribute. Refer to [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration). |
| additionalInfo.oobRefId | ID provided by the RP app to retrieve contextual information from the RP server. String. |
| modeResult | An object containing the server-generated QR code and/or raw data needed for your custom OOB mode. Has 3 attributes: qrCode.qrImage, push.status, and rawData. |
| modeResult.qrCode.qrImage | The server-generated QR Code. String (Base64-encoded PNG image). Returned if oobMode.qr is true. |
| modeResult.push.status | Status for push notification mode. Integer. Returned if oobMode.push is true. See START_OOB_AUTH's Push Notification Status Codes for possible push status values. |
| modeResult.rawData | Raw data to send to the second device when you are using your own mechanism in place of a QR code. String. Returned if oobMode.rawData is true. |

In the [response from VERIFY](/dpoa/docs/s3suite94-non-fido-authentication#response) when the operation is successful or continues, the method.data field for FIDO OOB Auth contains the fields below.

| **Field** | **Description** |
| --- | --- |
| additionalInfo | An object containing information from the client app running on the second device. Contains the attributes listed in the rows below. In order for the API Server to return this information, 1. The client app must have sent this information in the INIT_OOB_AUTH request’s message attribute. 2. Update the response filter configuration so the API Server returns the protocol, policy name, transaction ID, additional authenticator details, extension-related information, and OOB reference ID. By default, the API Server returns device information, authenticator handles, and FIDO2 authenticator attachment hints. Refer to [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration). |
| additionalInfo.authenticatorsResult | Authenticators that succeeded or failed to complete the OOB authentication operation. List<[AuthenticatorResult](/dpoa/docs/s3suite94-nok-nok-data-types#authenticatorresult)>. |
| additionalInfo.authenticatorsResult.transactionResult | If VERIFY performs a transaction, AuthenticatorResult also includes [TransactionResult](/dpoa/docs/s3suite94-nok-nok-data-types#transactionresult). |
| additionalInfo.authNotificationText | Dynamic push notification text. If the client app sends this in the request to INIT_VERIFY and the push is successful, then this string is returned when authentication succeeds. String. To send custom text from your client app, refer to *Sending Custom Push Notifications* in the [Android](/dpoa/docs/s3suite94-android-implementing-authentication-in-your-app#sending-custom-push-notifications), [iOS](/dpoa/docs/s3suite94-implementing-authentication-in-your-app#sending-custom-push-notifications) or [Web](/dpoa/docs/s3suite94-web-implementing-authentication-in-your-web-app#sending-custom-push-notifications) *Developer Guide*. |
| additionalInfo.device | A [DeviceDetail](/dpoa/docs/s3suite94-nok-nok-data-types#devicedetail) object containing information about the client. |
| additionalInfo.extensions | Message payload extensions received by the Server in FINISH_OOB_AUTH and INIT_OOB_AUTH requests. List<[Extension](/dpoa/docs/s3suite94-nok-nok-data-types#extension)>. |
| additionalInfo.headerExtensions | Protocol-specific header extensions. List<[HeaderExtension](/dpoa/docs/s3suite94-nok-nok-data-types#headerextension)>. |
| additionalInfo.oobRefId | ID provided by the RP app to retrieve contextual information from the RP server. String. In order for the API Server to return this information, send oobRefID in the method.data field of INIT_VERIFY's request. > oobRefId is present in the VERIFY operation following the FINISH_OOB_AUTH operation. |
| additionalInfo.policyName | Policy name used for the operation. String. |
| additionalInfo.protocol | The protocol used by the Server based on information from the request. String. One of UAF or Web. |
| additionalInfo.transaction.id | Transaction ID provided by RP to track a transaction. String. The transaction ID is provided in [INIT_ADAPTIVE](/dpoa/docs/s3suite94-rest-api)’s request. |
| push | An object containing information about the push notification. Contains the 3 attributes listed below. |
| push.handleLifetimeDays | Remaining lifetime of the push handle in days. Long. |
| push.pushHandle | Identifies the device that receives a push notification and then initiates an OOB authentication. A Base64-encoded string, maximum 4000 characters. |
| push.status | Result of the push notification. Integer. Also indicates status when the Server is unable to generate a new pushHandle because the maximum number of push notifications has been reached. This could be due to delivery or processing failures. |
| statusCode | FIDO Auth status code that reports the success of the requested operation. See Success Status Codes for the possible values. Integer. |

#### Email OTP

| **Field** | **Description** |
| --- | --- |
| additionalInfo | An object containing information from the client app that is initiating registration. Contains the 3 attributes listed in the rows below. In order for the API Server to return this information, 1. The client app must have sent this information in the [INIT_SETUP](/dpoa/docs/s3suite94-non-fido-registration#initsetup) request message attribute. 2. Update the response filter configuration so the API Server returns app information and payload extensions. By default, the API Server automatically returns device information. Refer to [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration). |
| additionalInfo.app | App information received from the client. [App](/dpoa/docs/s3suite94-nok-nok-data-types#app). |
| additionalInfo.device | A [DeviceDetail](/dpoa/docs/s3suite94-nok-nok-data-types#devicedetail) object containing information about the device that issued the [INIT_ADAPTIVE_REG](/dpoa/docs/s3suite94-adaptive-registration#initadaptivereg) request, such as the device’s unique ID, model, and manufacturer. |
| additionalInfo.extensions | Message payload extensions received by the Server in the [INIT_SETUP](/dpoa/docs/s3suite94-non-fido-registration#initsetup) request. List<[Extension](/dpoa/docs/s3suite94-nok-nok-data-types#extension)>. |
| authcounter | The total number of authentications performed using this registered email address. Present in the response from [LIST_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#listmethods) or [FETCH_USER_DATA](/dpoa/docs/s3suite94-manage-personally-identifiable-information-pii#fetchuserdata). |
| devices | An array of device information entries where each entry has a [device](/dpoa/docs/s3suite94-nok-nok-data-types#device) and [app](/dpoa/docs/s3suite94-nok-nok-data-types#app) field. Present in the response from [LIST_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#listmethods), [FETCH_USER_DATA](/dpoa/docs/s3suite94-manage-personally-identifiable-information-pii#fetchuserdata), [SUSPEND_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#suspendmethods), or [RESUME_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#resumemethods). |
| identifier | The email address where the passcode is sent. Sent in the request to [INIT_SETUP](/dpoa/docs/s3suite94-non-fido-registration#initsetup) or, optionally, [INIT_VERIFY](/dpoa/docs/s3suite94-non-fido-authentication#initverify). Present in the response from several operations. |
| otp | The one-time passcode. Sent in the request to [SETUP](/dpoa/docs/s3suite94-non-fido-registration#setup) or [VERIFY](/dpoa/docs/s3suite94-reference-restapi-fido-authentication#verify). |
| status | The registered method's status. One of the following: - 1: Active - 2: Deleted - 3: Suspended Present in the response from [LIST_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#listmethods) or [FETCH_USER_DATA](/dpoa/docs/s3suite94-manage-personally-identifiable-information-pii#fetchuserdata). |

#### External Authentication

| **Field** | **Description** |
| --- | --- |
| additionalInfo | An object containing information from the client app that is initiating registration. Contains the 3 attributes listed in the rows below. In order for the API Server to return this information, 1. The client app must have sent this information in the [INIT_SETUP](/dpoa/docs/s3suite94-non-fido-registration#initsetup) request message attribute. 2. Update the response filter configuration so the API Server returns app information and payload extensions. By default, the API Server automatically returns device information. Refer to [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration). |
| additionalInfo.app | App information received from the client. [App](/dpoa/docs/s3suite94-nok-nok-data-types#app). |
| additionalInfo.device | A [DeviceDetail](/dpoa/docs/s3suite94-nok-nok-data-types#devicedetail) object containing information about the device that issued the [INIT_SETUP](/dpoa/docs/s3suite94-non-fido-registration#initsetup) request, such as the device’s unique ID, model, and manufacturer. |
| additionalInfo.extensions | Message payload extensions received by the Server in the [INIT_SETUP](/dpoa/docs/s3suite94-non-fido-registration#initsetup) request. List<[Extension](/dpoa/docs/s3suite94-nok-nok-data-types#extension)>. |
| authcounter | The total number of authentications performed using this registered username. Present in the response from [LIST_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#listmethods) or [FETCH_USER_DATA](/dpoa/docs/s3suite94-manage-personally-identifiable-information-pii#fetchuserdata). |
| credential | This is a JWT generated by an RP server that performs an external authentication method. Sent in a request for an [INIT_ADAPTIVE](/dpoa/docs/s3suite94-rest-api) or [VERIFY](/dpoa/docs/s3suite94-reference-restapi-fido-authentication#verify) operation. If you have a custom External Authentication plugin, the credential could be different. |
| devices | An array of device information entries where each entry has a [device](/dpoa/docs/s3suite94-nok-nok-data-types#device) and [app](/dpoa/docs/s3suite94-nok-nok-data-types#app) field. Present in the response from [LIST_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#listmethods), [FETCH_USER_DATA](/dpoa/docs/s3suite94-manage-personally-identifiable-information-pii#fetchuserdata), [SUSPEND_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#suspendmethods), or [RESUME_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#resumemethods). |
| status | The registered method's status. One of the following: - 1: Active - 2: Deleted - 3: Suspended Present in the response from [LIST_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#listmethods) or [FETCH_USER_DATA](/dpoa/docs/s3suite94-manage-personally-identifiable-information-pii#fetchuserdata). |

> If the user fails verification with the external authentication method, the API Server responds with a 401 HTTP status code. Additionally, the response payload includes an [additionalErrorInfo](/dpoa/docs/s3suite94-nok-nok-data-types#additionalerrorinfo) object so you can determine the cause of the error.

```plaintext
{
    "additionalErrorInfo": {
        "outcome": "ExternalAuthFailed"
    }
}
```

#### Photo ID

| **Field** | **Description** |
| --- | --- |
| additionalInfo | An object containing information from the client app that is initiating registration. Contains the 3 attributes listed in the rows below. In order for the API Server to return this information, 1. The client app must have sent this information in the [INIT_SETUP](/dpoa/docs/s3suite94-non-fido-registration#initsetup) request message attribute. 2. Update the response filter configuration so the API Server returns app information and payload extensions. By default, the API Server automatically returns device information. Refer to [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration). |
| additionalInfo.app | App information received from the client. [App](/dpoa/docs/s3suite94-nok-nok-data-types#app). |
| additionalInfo.device | A [DeviceDetail](/dpoa/docs/s3suite94-nok-nok-data-types#devicedetail) object containing information about the device that issued the [INIT_SETUP](/dpoa/docs/s3suite94-non-fido-registration#initsetup) request, such as the device’s unique ID, model, and manufacturer. |
| additionalInfo.extensions | Message payload extensions received by the Server in the [INIT_SETUP](/dpoa/docs/s3suite94-non-fido-registration#initsetup) request. List<[Extension](/dpoa/docs/s3suite94-nok-nok-data-types#extension)>. |
| authcounter | The total number of authentications performed using this registered Photo ID. Present in the response from [LIST_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#listmethods) or [FETCH_USER_DATA](/dpoa/docs/s3suite94-manage-personally-identifiable-information-pii#fetchuserdata). |
| devices | An array of device information entries where each entry has a [device](/dpoa/docs/s3suite94-nok-nok-data-types#device) and [app](/dpoa/docs/s3suite94-nok-nok-data-types#app) field. Present in the response from [LIST_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#listmethods), [FETCH_USER_DATA](/dpoa/docs/s3suite94-manage-personally-identifiable-information-pii#fetchuserdata), [SUSPEND_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#suspendmethods), or [RESUME_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#resumemethods). |
| identifier | A Server-computed hash based on the content of the Photo ID. |
| scanReferenceID | The scan reference ID returned by NetVerify after it receives the images sent by the client app. Used by the Server when it polls the NetVerify server about the verification status of the ID document. Sent in the request to [INIT_SETUP](/dpoa/docs/s3suite94-non-fido-registration#initsetup) or [INIT_VERIFY](/dpoa/docs/s3suite94-non-fido-authentication#initverify). |
| status | The registered method's status. One of the following: - 1: Active - 2: Deleted - 3: Suspended Present in the response from [LIST_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#listmethods) or [FETCH_USER_DATA](/dpoa/docs/s3suite94-manage-personally-identifiable-information-pii#fetchuserdata). |

#### SMS OTP

| **Field** | **Description** |
| --- | --- |
| additionalInfo | An object containing information from the client app that is initiating registration. Contains the 3 attributes listed in the rows below. In order for the API Server to return this information, 1. The client app must have sent this information in the [INIT_SETUP](/dpoa/docs/s3suite94-non-fido-registration#initsetup) request message attribute. 2. Update the response filter configuration so the API Server returns app information and payload extensions. By default, the API Server automatically returns device information. Refer to [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration). |
| additionalInfo.app | App information received from the client. [App](/dpoa/docs/s3suite94-nok-nok-data-types#app). |
| additionalInfo.device | A [DeviceDetail](/dpoa/docs/s3suite94-nok-nok-data-types#devicedetail) object containing information about the device that issued the [INIT_SETUP](/dpoa/docs/s3suite94-non-fido-registration#initsetup) request, such as the device’s unique ID, model, and manufacturer. |
| additionalInfo.extensions | Message payload extensions received by the Server in the [INIT_SETUP](/dpoa/docs/s3suite94-non-fido-registration#initsetup) request. List<[Extension](/dpoa/docs/s3suite94-nok-nok-data-types#extension)>. |
| authcounter | The total number of authentications performed using this registered phone number. Present in the response from [LIST_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#listmethods) or [FETCH_USER_DATA](/dpoa/docs/s3suite94-manage-personally-identifiable-information-pii#fetchuserdata). |
| devices | An array of device information entries where each entry has a [device](/dpoa/docs/s3suite94-nok-nok-data-types#device) and [app](/dpoa/docs/s3suite94-nok-nok-data-types#app) field. Present in the response from [LIST_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#listmethods), [FETCH_USER_DATA](/dpoa/docs/s3suite94-manage-personally-identifiable-information-pii#fetchuserdata), [SUSPEND_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#suspendmethods), or [RESUME_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#resumemethods). |
| identifier | The phone number, including country code, where the passcode is sent. Sent in the request to [INIT_SETUP](/dpoa/docs/s3suite94-non-fido-registration#initsetup) or, optionally, [INIT_VERIFY](/dpoa/docs/s3suite94-non-fido-authentication#initverify). Present in the response from several operations. |
| otp | The one-time passcode. Sent in the request to [SETUP](/dpoa/docs/s3suite94-non-fido-registration#setup) or [VERIFY](/dpoa/docs/s3suite94-reference-restapi-fido-authentication#verify). |
| status | The registered method's status. One of the following: - 1: Active - 2: Deleted - 3: Suspended Present in the response from [LIST_METHODS](/dpoa/docs/s3suite94-manage-non-fido-registrations#listmethods) or [FETCH_USER_DATA](/dpoa/docs/s3suite94-manage-personally-identifiable-information-pii#fetchuserdata). |

## AuthenticatorInfo

This data structure contains details about a registered authenticator. AuthenticatorInfo is returned in the [response from LIST_REG](/dpoa/docs/s3suite94-manage-fido-registrations#response).

The Authentication Server returns different fields in AuthenticatorInfo depending on optionsData.needDetails's value in LIST_REG's request and which fields in AuthenticatorInfo you configured the API Server's response filter to return. Refer to [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration).

> The attributes listed below are indicative but not exhaustive. The Server may return additional attributes.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| aaguid | String | The FIDO2 Authenticator Attestation GUID. Present for a FIDO2 authenticator when optionsData.needDetails = 3 in LIST_REG’s request. |
| aaid | String | The UAF Authenticator Attestation ID. Present for a UAF authenticator when optionsData.needDetails = 3 in LIST_REG’s request. |
| acki | String | The Attestation Certificate public Key Identifier for U2F authenticator metadata. Present for a FIDO2 authenticator when optionsData.needDetails = 3 in LIST_REG’s request. |
| appAtts | Array of [AppAttest](/dpoa/docs/s3suite94-nok-nok-data-types#authenticatorinfo) | An array of AppAttests. AppAttests contains authenticator attributes specific to the iOS app integrity credential. Optionally present only for an iOS FIDO2 or iOS UAF authenticator to validate the app’s integrity. |
| authCount | Integer | The total number of authentications performed by this registered authenticator. |
| authenticatorName | Alphanumeric string. 128 character maximum. | The name of the registered authenticator. |
| createdTimeStamp | Long | The time when the authenticator was registered for the user. |
| credentialId | String | The unique identifier identifying a WebAuthn authenticator's public key credential source and its authentication assertions sent by the client and remembered by the Auth Server. Present for a FIDO2 authenticator when optionsData.needDetails = 3 in [LIST_REG’s request](/dpoa/docs/s3suite94-manage-fido-registrations). |
| description | String | Describes the registered authenticator. |
| handle | Alphanumeric string. 4000 character maximum. | String that uniquely identifies the registered authenticator. |
| keyID | String | A unique identifier for the authenticator, within the scope of an AAID. Present for a UAF authenticator when optionsData.needDetails = 3 in [LIST_REG’s request](/dpoa/docs/s3suite94-manage-fido-registrations#listreg). |
| lastUsedTimeStamp | Long | The time when the authenticator was last used. Present if optionsData.needDetails = 2 or 3 in [LIST_REG’s request](/dpoa/docs/s3suite94-manage-fido-registrations#listreg). |
| publicKey | String | The authenticator’s public key that was received during registration. Present for a UAF authenticator when optionsData.needDetails = 3 in [LIST_REG’s request](/dpoa/docs/s3suite94-manage-fido-registrations#listreg). |
| status | Integer | The registered authenticator’s status: - 1: Active - 2: Deleted - 3: Suspended |

## AuthenticatorResult

AuthenticatorResult is a data structure that represents authenticator details. It is returned in the response from REST API operations. If multiple authenticators were used during an operation, then each authenticator has a corresponding AuthenticatorResult returned.

The API Server returns AuthenticatorResult in the response provided that:

- The value of the optionsData.needDetails field in the request is 2 or 3.
- You configured the API Server's response filter to return data. By default, the API Server returns the handle and attachmentHints fields. You can configure the API Server to return more or less data by modifying its response filter configuration. Refer to [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration).

> The fields listed in the table are indicative but not exhaustive. The server may return additional fields.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| aaguid | String | The FIDO2 Authenticator Attestation GUID. |
| aaid | String | The Authenticator Attestation ID (AAID). |
| appAtt | [AppAttest](/dpoa/docs/s3suite94-nok-nok-data-types#appattest) | Present only if the app attest extension is requested as per the policy on an Apple platform. |
| assertionExtensions | List<HeaderExtension> | Represents authenticator assertion extension data per the UAF specification. |
| attachmentHints | Array of strings | Provides hints about how the authenticator communicates with the client app. Valid values: - ble: Bluetooth Low Energy (BLE) - hybrid: A combination of data transport and proximity mechanisms. - internal: The authenticator is a platform authenticator. - nfc: Near Field Communication (NFC) - usb: Removable USB - smart-card: The authenticator can be contacted over an ISO/IEC 7816 smart card. For more information, refer to the WebAuthn spec: [https://w3c.github.io/webauthn/#enum-transport](https://w3c.github.io/webauthn/#enum-transport) |
| attestationType | Integer | The type of attestation used by the authenticator. Based on the FIDO spec's authenticator attestation types, see: [https://fidoalliance.org/specs/common-specs/fido-registry-v2.2-ps-20220523.html#authenticator-attestation-types](https://fidoalliance.org/specs/common-specs/fido-registry-v2.2-ps-20220523.html#authenticator-attestation-types). Has the following differences: - "ecdaa" attestation is not supported. - The value returned is the decimal representation of the Hex number. - 0x3e07 = 15879 (basic_full) - 0x3e08 = 15880 (basic_surrogate or self-attestation) - 0x3e0a = 15882 (attca) - 0x3e0c = 15884 (anonca) - 0x0000 = 0 (none) |
| attestationFormat | String | The [attestation statement format identifier](https://www.w3.org/TR/webauthn-2/#attestation-statement-format-identifier) |
| attestationCertSubjectD | String | The subject of the credential certificate. Present based on the attestationFormat received. Applicable to webauthn authenticator. |
| attestationTypeName | String | The [attestation type name](https://www.w3.org/TR/webauthn/#sctn-attestation-types). |
| attestationStatus | String | The outcome of the attestation processing for webauthn. Value can be one of: - SUCCESS - FAILED - UNAVAILABLE - ENTERPRISE_FAILED |
| authenticatorAttachment | String | Describes the authenticator’s attachment modalities, if available from the client. Valid values: - platform: A [platform attachment](https://w3c.github.io/webauthn/#platform-attachment). - cross-platform: a [cross-platform](https://w3c.github.io/webauthn/#cross-platform-attachment) or roaming attachment. For more information, refer to the [WebAuthn spec](https://w3c.github.io/webauthn/#enum-attachment). |
| authenticatorExtensions | List<HeaderExtension> | Represents authenticator non-TLV encoded extension data per the UAF specification. |
| authenticatorName | Alphanumeric string. 128 character maximum | The name of the authenticator. |
| authenticatorSerialNumber | String | The unique serial number of the authenticator extracted from the credential certificate. Present based on the attestationFormat received. Applicable for webauthn authenticator. |
| authenticatorVersion | Integer | The authenticator version. |
| backedUp | Boolean | Applicable only for a synced passkey. - true: The synced passkey was backed up - false: The synced passkey was not backed up |
| backUpEligible | Boolean | Indicates if the authenticator can be backed up. Only true for synced passkeys. |
| credentialID | String | A probabilistically-unique [byte sequence](https://infra.spec.whatwg.org/#byte-sequence) identifying a [public key credential source](https://www.w3.org/TR/webauthn-2/#public-key-credential-source) and its [authentication assertions](https://www.w3.org/TR/webauthn-2/#authentication-assertion). Applicable for webauthn authenticator. |
| dpk | DevicePublicKey | Present only if the authenticator is a synced passkey. Includes details about the Device Public Key. |
| handle | String | Unique identifier for the authenticator. |
| headerExtensions | List<HeaderExtension> | Represents protocol-specific header extensions. |
| status | Integer | The status code. > This may or may not be applicable. |
| transactionResult | TransactionResult | Represents the result from a transaction. |
| userPresence | Boolean | - true: user is present - false: user is not present |
| userVerification | Boolean | - true: user is verified - false: user is not verified. For example, userVerification is true if the authenticator verified the user via fingerprint. |
| uvi | String | The user verification index. Used for Android. Indicates which biometric authentication method, which finger for example. |
| uvm | List<[Uvm](/dpoa/docs/s3suite94-nok-nok-data-types#uvm)> | Represents the fido.uaf.uvm user verification method extension. An object that contains userVerificationMethod, keyProtection, and matcherProtection. Below is a sample uvm field from a REST API response. startcode"uvm": [ { "userVerificationMethod": "presence", "keyProtection": "hardware", "matcherProtection": "software" } ] |
| uviStatus | String | The status of UVI. |
| uvs | String | The user verification state. Used for iOS. Indicates which biometric authentication method, which finger for example. |
| uvsStatus | Integer | The status of UVS. |

AuthenticatorResult can be returned as a part of the response payload from the following REST API methods:

- [FINISH_REG](/dpoa/docs/s3suite94-fido-registration#finishreg)
- [STATUS_OOB_REG](/dpoa/docs/s3suite94-out-of-band-registration#statusoobreg)
- [STATUS_OOB_AUTH](/dpoa/docs/s3suite94-out-of-band-authentication#statusoobauth)
- [FINISH_OOB_REG](/dpoa/docs/s3suite94-out-of-band-registration#finishoobreg)
- [FINISH_OOB_AUTH](/dpoa/docs/s3suite94-out-of-band-authentication#finishoobauth)
- [VERIFY](https://docs.onespan.com/dpoa/docs/s3suite94-reference-restapi-fido-authentication#verify)
- [LIST_REG](/dpoa/docs/s3suite94-manage-fido-registrations#listreg)
- [FETCH_USER_DATA](/dpoa/docs/s3suite94-manage-personally-identifiable-information-pii#fetchuserdata)

### Status Codes

If the authenticator was used in a registration or authentication operation, the Auth Server returns one of the following status codes in AuthenticatorResult.Status.

| **Server Status Code** | **Description** | **Examples** |
| --- | --- | --- |
| 4000 | OK. Operation completed | Authentication or registration completed successfully. |
| 4002 | OK. Optional security checks failed | Applies to both registration and authentication. Non-critical FIDO policy check failures. For example: - The app attest extension was not received or was not processed successfully during authentication. - Attestation was not received during registration. |
| 4400 | Registration NotFound Exception | Failed to authenticate because the registration does not exist on Server for a specific user. > This error code is applicable for the UAF protocol. |
| 4402 | Security Exception | Applies to both registration and authentication. Examples: - Failed to validate the attestation. - Failed to validate Server challenge. - Failed to validate the Server data. - Failed to locate authenticator metadata. - Challenge replay detected. - Failed to validate extension data. - Failed to validate user name. |
| 4403 | Policy Exception | Applies to both registration and authentication. The authenticator doesn't match the FIDO policy. |
| 4404 | Internal Server Error | Applies to both registration and authentication. Examples: - Failed to write to the database. - Failed to read from the database. - Failed to connect to the database. - Failed to read properties. |
| 4410 | Authenticator Revoked | Applies to authentication only. The authenticator is considered revoked by the Server. Authenticator state is not valid. The certificate used for authentication was revoked. |
| 4455 | Authenticator suspended | Applies to authentication only. The authenticator is suspended. This generally only applies to FIDO2 authenticators. |

## AuthSequence

AuthSequence is a data structure that represents the list of authentication methods that the Server returns when an Adaptive Rule succeeds and has a specific action. For Registration Decision Rules, these actions are SUGGEST_REGISTRATION and ENFORCE_REGISTRATION; for Authentication Rules, this action is TRIGGER_AUTHENTICATION.

The App SDK presents methods from the returned AuthSequences to the user. After the user selects a method, the App SDK interacts with them to either register or verify them with that method. The App SDK Developer guides the user to process all the methods in one sequence. As the user selects a method, the Server and App SDK adjust which sequences are still viable given the user's selection.

If the Adaptive Rule has a PostOperation Check that forces the end user to authenticate with the remaining methods in AuthSequence, you can supply a reason explaining why the user needs to verify their identity with these additional methods.

When you define a sequence for an Adaptive Rule, you can assign a reason code for that sequence. See Step 5D. [Enter Sequences](/dpoa/docs/configure-adaptive-rulesets). To define the reason code's text explanation, see [Customize the UI in the App SDK Using JSON](/dpoa/docs/s3suite94-replacing-strings#explaining-to-the-user-why-additional-authentication-is-required).

> The fields listed in the table are indicative but not exhaustive. The Server may return additional fields.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| id | String | Unique identifier for the authentication sequence. Required. |
| methods | Set<[Authentication Method](/dpoa/docs/s3suite94-nok-nok-data-types#authentication-method)> | The set of authentication methods that can be used to complete either registration or authentication. Required. |
| reason | String | A reason code that explains why the end user is being prompted to use the authentication methods in this AuthSequence to authenticate. The App SDK takes care of mapping the reason code to a text explanation that can be displayed to the end user in the client app. Optional. |

## ChannelBinding

This data structure contains channel binding data that is obtained from the TLS endpoint of the secure connection between the Client and the Server. It binds the TLS channel to the FIDO operation for additional security. Your application can obtain the channel binding information from the TLS endpoint in your infrastructure and send the information in the REST API request payload.

ChannelBinding consists of the following fields:

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| cid_pubkey | String | Optional. The public key of the public-private key pair generated by the client application. This is currently unused. |
| serverEndPoint | String | Optional. The TLS server certificate. The certificate includes a Base64url-encoded hash function. |
| tlsServerCertificate | String | Optional. The DER-encoded TLS server certificate. The certificate is Base64url-encoded. |
| tlsUnique | String | Optional. The TLS channel Finished structure (RFC5929). The structure is Base64url-encoded. |

## Device

Device is a data structure containing device information used by [Registration](/dpoa/docs/s3suite94-nok-nok-data-types#registration). Device is generated by the Nok Nok App SDK and is returned as part of the server response by [LIST_REG](/dpoa/docs/s3suite94-manage-fido-registrations#listreg). Device contains the attributes shown in the table below.

The API Server returns Device in the response provided that the value of the optionsData.needDetails field in the request is 2 or 3.

By default, the API Server returns all the fields in this structure. You can configure the API Server to return fewer fields by modifying its response filter configuration. Refer to [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration).

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| type | String | The device type: android, ios, or browser. |
| id | String | The unique identifier for the device. This is generated by the Nok Nok App SDK. The device ID is unique per app and device. So different apps on the same device have different device IDs. Device IDs remain the same when an app is uninstalled and reinstalled. Device IDs are different after a factory reset. Javascript Device IDs change after clearing the browser local store. |
| info | String | The device name, for example, Hildy’s phone. |
| manufacturer | String | The manufacturer of the device |
| model | String | The device’s model |
| os | String | The device’s operating system and version |

## DeviceDetail

DeviceDetail is a data structure containing device information you use when working with the REST API. DeviceDetail is generated by the Nok Nok App SDK and is returned as a server response by some of the REST API operations. DeviceDetail consists of the following fields:

> The attributes listed in the table are indicative but not exhaustive. The Server may return additional fields.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| id | String | The unique identifier for the device. This is generated by the Nok Nok App SDK. The device ID is unique per app and device. So different apps on the same device have different device IDs. Device IDs remain the same when an app is uninstalled and reinstalled. Device IDs change after a factory reset. JavaScript Device IDs change after clearing the browser's local store. |
| info | String | The device name (for example, My iPhone). |
| manufacturer | String | The name of the manufacturer. |
| model | String | Model details of the device. |
| os | String | The operating system of the device. |
| push |  | An object containing information about a new push handle. Contains the 3 attributes listed below. Present in [LIST_REG](/dpoa/docs/s3suite94-manage-fido-registrations#listreg)'s response when needDetails= 3 and there is a push notification ID associated with this device. |
| push.pushHandle | String | The device that receives a push notification and initiates an OOB authentication. A Base64-encoded string, maximum 4000 characters. |
| push.handleLifetimeDays | Long | Remaining lifetime of the push handle in days. |
| push.createdTimeStamp | String | Creation date and time of push handle in UTC format. |
| type | String | The device type: android, ios, or browser. |

## DevicePublicKey

DevicePublicKey is a data structure that represents information about a device-bound key, also known as a Device Public Key (DPK). It is technically an authenticator extension and can only be present for an authenticator that is a synced passkey. A DPK provides additional assurance that the passkey is valid by supplying information about the user's device.

This data structure is based on the devicePubKey extension in the WebAuthn draft specification: [https://w3c.github.io/webauthn/#sctn-device-publickey-extension](https://w3c.github.io/webauthn/#sctn-device-publickey-extension). DevicePublicKey is optionally returned in the response of REST API operations. Refer to the list at the end of this section.

> The fields listed in the following table are indicative, but not exhaustive. The Server may return additional fields.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| aaguid | String | The FIDO2 Authenticator Attestation GUID. |
| attestationFormat | String | The attestation for the DPK. Currently, only the value "none" is supported. For a detailed description, see [https://www.iana.org/assignments/webauthn/webauthn.xhtml#webauthn-attestation-statement-format-ids](https://www.iana.org/assignments/webauthn/webauthn.xhtml#webauthn-attestation-statement-format-ids) |
| description | String | Describes the DPK. |
| handle | String | Unique identifier for the DPK. |
| scope | Integer | The scope of the DPK. - 0: Scope is the entire device, in other words affects all apps - 1: Scope is per app |
| state | String | The outcome after the Auth Server processed the devicePubKey extension. - NOT_APPLICABLE: The DPK extension is not applicable. For example, the information may pertain to a UAF authenticator, not a synced passkey. - UNAVAILABLE: The DPK extension was not sent in the request. - INVALID: The DPK extension is invalid. - UNTRUSTED: The device is not trusted, additional authentication may be necessary. - TRUSTED: The device is trusted. |
| status | Integer | The status of the DPK stored in the Auth Server's database. One of the following values: - 0: Pending (not yet trusted, indicates that this is the first time the DPK was used) - 1: Active (trusted) - 3: Active DPK, but suspended - 6: Pending DPK, but suspended |

The following REST API operations can return DevicePublicKey as a part of the response payload.

- [FINISH_REG](/dpoa/docs/s3suite94-fido-registration#finishreg)
- [FINISH_OOB_REG](/dpoa/docs/s3suite94-out-of-band-registration#finishoobreg)
- [STATUS_OOB_REG](/dpoa/docs/s3suite94-out-of-band-registration#statusoobreg)
- [FINISH_OOB_AUTH](/dpoa/docs/s3suite94-out-of-band-authentication#finishoobauth)
- [STATUS_OOB_AUTH](/dpoa/docs/s3suite94-out-of-band-authentication#statusoobauth)
- [VERIFY](/dpoa/docs/s3suite94-reference-restapi-fido-authentication#verify)
- [LIST_REG](/dpoa/docs/s3suite94-manage-fido-registrations#listreg)
- [FETCH_USER_DATA](/dpoa/docs/s3suite94-manage-personally-identifiable-information-pii#fetchuserdata)

## Extension

Extension is a data structure that represents extension details. App SDK users can send various kinds of information in an extensions structure like flags to control behavior and data like location, jailbreak signal, account name, correlation ID, transaction text, and so on. Extension is returned in the response of several REST API operations. It consists of the following fields:

> The fields listed in the following table are indicative, but not exhaustive. The Server may return additional fields.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| data | String | The extension specific data. |
| id | String | Unique identifier for the extension. |
| operation | String | The operation ID in which the extension was received |

The Authentication Server returns Extension in the response of a REST API operation provided that:

- The value of the optionsData.needDetails field in the request is 2 or 3.
- You configured the API Server's response filter to return Extension.

By default, the API Server does not return this structure. You can configure the API Server to return one or more fields by modifying its response filter configuration. Refer to [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration).

The following REST API operations can return an array of Extension as a part of the response payload. Unless noted otherwise, extensions are received in the operation’s request.

- [INIT_REG](/dpoa/docs/s3suite94-fido-registration#initreg)
- [FINISH_REG](/dpoa/docs/s3suite94-fido-registration#finishreg) ⇒ contains extensions received in INIT_REG and FINISH_REG requests
- [DELETE_REG](/dpoa/docs/s3suite94-rest-api)
- [START_OOB_AUTH](/dpoa/docs/s3suite94-out-of-band-authentication#startoobauth)
- [STATUS_OOB_REG](/dpoa/docs/s3suite94-out-of-band-registration#statusoobreg) ⇒ contains extensions received in INIT_OOB_REG and FINISH_OOB_REG requests
- [STATUS_OOB_AUTH](/dpoa/docs/s3suite94-out-of-band-authentication#statusoobauth) ⇒ contains extensions received in INIT_OOB_AUTH and FINISH_OOB_AUTH requests
- [INIT_OOB_AUTH](/dpoa/docs/s3suite94-out-of-band-authentication#initoobauth)
- [INIT_OOB_REG](/dpoa/docs/s3suite94-out-of-band-registration#initoobreg)
- [FINISH_OOB_AUTH](/dpoa/docs/s3suite94-out-of-band-authentication#finishoobauth) ⇒ contains extensions received in INIT_OOB_AUTH and FINISH_OOB_AUTH requests
- [FINISH_OOB_REG](/dpoa/docs/s3suite94-out-of-band-registration#finishoobreg) ⇒ contains extensions received in INIT_OOB_REG and FINISH_OOB_REG requests

## HeaderExtension

HeaderExtension is a data structure modeled after the FIDO specification's [extension dictionary](https://fidoalliance.org/specs/fido-uaf-v1.2-ps-20201020/fido-uaf-protocol-v1.2-ps-20201020.html#extension-dictionary). App SDK users can use this to send UAF protocol extension data. HeaderExtension is returned in the response of some REST API operations. It consists of the following fields:

> The fields listed in the following table are indicative, but not exhaustive. The Server may return additional fields.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| data | String | The extension specific data. |
| failIfUnknown | Boolean | - true: an unknown extension results in an error. - false: ignore the unknown extension |
| id | String | Unique identifier for the extension. |

The API Server returns Extension in the response of a REST API operation provided that:

- The value of the optionsData.needDetails field in the request is 2 or 3.
- You configured the API Server's response filter to return HeaderExtension.

> By default, the API Server does not return this structure. You can configure the API Server to return one or more fields by modifying its response filter configuration. Refer to [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration).

The following REST API operations can return an array of HeaderExtension as a part of the response payload. Unless noted otherwise, extensions are received in the operation’s request.

- [FINISH_REG](/dpoa/docs/s3suite94-fido-registration#finishreg)
- [FINISH_OOB_REG](/dpoa/docs/s3suite94-out-of-band-registration#finishoobreg)
- [STATUS_OOB_REG](/dpoa/docs/s3suite94-out-of-band-registration#statusoobreg) (HeaderExtension was received in the FINISH_OOB_REG call that preceded STATUS_OOB_REG)
- [FINISH_OOB_AUTH](/dpoa/docs/s3suite94-out-of-band-authentication#finishoobauth)
- [STATUS_OOB_AUTH](/dpoa/docs/s3suite94-out-of-band-authentication#statusoobauth) (HeaderExtension was received in the FINISH_OOB_AUTH call that preceded STATUS_OOB_AUTH)
- [VERIFY](/dpoa/docs/s3suite94-reference-restapi-fido-authentication#verify) (HeaderExtension was received in the request or, for OOB performed during Adaptive Authentication, in a FINISH_OOB_AUTH call)

## OptionsData

The optionsData attribute is sent from the App SDK to the API Server. It is a mechanism for passing in custom data specific to the operation. It is a JSON structure with the following optional fields.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| needDetails | Integer | An attribute used to indicate the level of the details returned in the additionalInfo field in the response. One of: - 2 (default): Return information about the app and device. Actual data varies depending on the REST API operation you use. - 3: Used only by [LIST_REG](/dpoa/docs/s3suite94-manage-fido-registrations#listreg). Return information about the protocol family, registered authenticator ([AuthenticatorInfo](/dpoa/docs/s3suite94-nok-nok-data-types#authenticatorinfo)), and push handle ([DeviceDetail](/dpoa/docs/s3suite94-nok-nok-data-types#devicedetail).push.pushHandle). > You must also modify the API Server's response filter so the data is returned. For information about the type of data that can be returned in additionalInfo, see [AdditionalInfo](/dpoa/docs/s3suite94-nok-nok-data-types#additionalinfo). To modify the filtering done on additionalInfo, see [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration). |
| policyName | String, max 256 characters | A FIDO registration policy name configured and stored on the Authentication Server. The Server uses the policy to determine which FIDO authenticators are valid to register for Adaptive Authentication. This attribute applies to [INIT_REG](/dpoa/docs/s3suite94-fido-registration#initreg) and [START_OOB_REG](/dpoa/docs/s3suite94-out-of-band-registration#startoobreg). If present, it overrides the policyType attribute below. |
| policyType | String | A policy type that maps to a policy name configured on the Authentication Server. Only use this if you define app-specific policy types. In other words, you configured additional policy types by adding them to the app_specified_policies field in the PolicyPlugin's configuration (default_config). Use the Admin Console to import this configuration. This attribute applies to [INIT_REG](/dpoa/docs/s3suite94-fido-registration#request), [START_OOB_REG](/dpoa/docs/s3suite94-out-of-band-registration#startoobreg), and [START_OOB_AUTH](/dpoa/docs/s3suite94-out-of-band-authentication#startoobauth). See [Create a Policy Plugin](/dpoa/docs/s3suite94-create-a-policy-plugin) for further information. |
| transactionText | String, very large | Text that the client displays to the user to verify and authorize a secure transaction. |

In the example below, an app starts an OOB authentication request, passing in optionsData with the transactionText field set. The request might look as follows:

```plaintext
{
    "operation":"START_OOB_AUTH",
    "oobMode":{"qr":true,"push":false,"rawData":true},
    "transaction":{"id":"<some-unique-id>"},
    "sessionData":{"sessionKey": "<session JWT>"},
    "optionsData":{"transactionText":"Total price to pay is $100"}
}
```

## Registration

Registration contains information about the registered authenticators for a user. This information is contained in [Device](/dpoa/docs/s3suite94-nok-nok-data-types#device), [App](/dpoa/docs/s3suite94-nok-nok-data-types#app), and a list made up of [AuthenticatorInfo](/dpoa/docs/s3suite94-nok-nok-data-types#authenticatorinfo). The server returns an array of Registration in the response for [LIST_REG](/dpoa/docs/s3suite94-manage-fido-registrations#listreg) and [FETCH_USER_DATA](/dpoa/docs/s3suite94-manage-personally-identifiable-information-pii#fetchuserdata).

If the value of the optionsData.needDetails field in the request body is set to 3 and you configured the API Server's response filter, then additional information about each authenticator is returned in AuthenticatorInfo. Refer to the documentation about [AuthenticatorInfo](/dpoa/docs/s3suite94-nok-nok-data-types#authenticatorinfo) for details.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| app | [App](/dpoa/docs/s3suite94-nok-nok-data-types#app) object | Information about the user’s app that utilizes the authenticators. |
| authenticators | List<[AuthenticatorInfo](/dpoa/docs/s3suite94-nok-nok-data-types#authenticatorinfo)> | Information about the registered authenticators for the associated device and app. |
| device | [Device](/dpoa/docs/s3suite94-nok-nok-data-types#device) object | A JSON-formatted structure that contains information about the user’s device. |

## RulesResult

RulesResult is a data structure that contains all the FIDO policy risk rules whose condition evaluates to true. This is only present if the FIDO policy had risk rules defined for it and at least one of those rules succeeded. It is returned in the response of REST API operations and consists of the fields shown below.

The API Server returns RulesResult in the response of a REST API operation provided that:

- The value of the optionsData.needDetails field in the request is 2 or 3.
- You configured the API Server's response filter to return RulesResult. By default, the API Server does not return this structure. You can configure the API Server to return one or more fields by modifying its response filter configuration. Refer to [Response Filter Configuration](/dpoa/docs/s3suite94-main#response-filter-configuration).

> The fields listed in the table are indicative but not exhaustive. The API Server may return additional fields.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| action | String | Indicates the final action/outcome of the operation. ALLOW or DENY are the two actions performed by the rules. |
| matchedRules | List | Includes information about all rules that are matched during policy evaluation. |
| matchedRules.group | String | Group name to which the template belongs. |
| matchedRules.name | String | Name of the rule. |
| matchedRules.riskScore | Integer | Risk score of the configured rule. |
| matchedRules.template | String | Template name used to configure the rule. |
| riskThresholdRule | Object | Information about the RiskThreshold rule, if it was defined for the FIDO policy. |
| riskThresholdRule.aboveThreshold | Boolean | - true: RiskScore ≥ threshold - false: RiskScore < threshold |
| riskThresholdRule.riskScore | Integer | The sum of all the risk scores from succeeding risk rules. |
| riskThresholdRule.threshold | Integer | The defined threshold value for riskThreshold rule. |

## SessionData

The sessionData stores session-related information. It is initially created as a result of authentication and is required for subsequent operations. It has the following fields.

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| emv3dsData | Object | Output. Optional. A JSON Web Signature (JWS) object containing an EMV 3DS FIDO blob. It is returned when the EMV 3DS Session plugin is enabled and under the following conditions: - Regular FIDO: Successful registration, authentication, or transaction confirmation. - Adaptive Authentication: When there is a successful adaptive rule that was defined to return a 3DS FIDO blob. |
| exp | Integer | Output. Optional. Contains the session expiration time in seconds since UNIX epoch |
| pushHandle | String | Input. Optional. A handle (unique ID) used to trigger push notification to a specific device. |
| sessionKey | Object | Session-related data for maintaining the session state for a specific user on the client side. In the request, sessionKey is optional for authentication REST API operations but required for other operations. The value must be a JWT. Returned in the response by REST API operations that perform authentication. |
| tcToken | Object | Output. Optional. The Transaction Confirmation Token generated by the API Server for successfully confirmed transactions. The value is a JWT. Contains the transaction ID as a claim. See [Transaction Confirmation Token](/dpoa/docs/s3suite94-claim-set#transaction-confirmation-token). |
| userName | String | Input. Optional. Specifies the authenticating user name, if known. The user name must be unique across all users in a tenant. This attribute is used for authentication operations. The API Server must have been configured for FIDO2 to use this attribute. See [Configure FIDO2 authentication](/dpoa/docs/s3suite94-configure-a-fido2-authentication-method). |

sessionData can be passed into the API Server and returned by the API Server. API Server's default session plugins expect and provide sessionData as a JSON object in the request and response JSON payload.

If you have implemented a custom session plugin, that plugin could use headers or cookies to transport session data. In the Android and iOS App SDKs, there is a flag to obtain session data fields from the payload. On the Web, cookies are automatically handled by the browser. Depending on the approach you use, the App SDK handles sessionData's attributes as described below

- Use different cookies for each of sessionData's attributes. The App SDK gets each field from sessionData and puts it into an individual cookie in the request to the API Server. The App SDK constructs a sessionData object from the response's cookies before returning sessionData to the app.
- Within individual headers for fields. The App SDK puts sessionData's attributes into headers and constructs a sessionData object from the response headers before returning to the app.

## TransactionResult

transactionResult is a data structure that contains the results from an executed transaction. transactionResult is returned in the response of the REST API operations listed below. It is returned for transactions performed with either the UAF or FIDO2 protocol. It has the following fields:

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| hash | String | Hashed value of transaction.text. transaction.text can come from [START_OOB_AUTH](/dpoa/docs/s3suite94-out-of-band-authentication#startoobauth) or [INIT_ADAPTIVE](/dpoa/docs/s3suite94-adaptive-authentication#initadaptive). |
| hashAlgorithm | String | Algorithm used to hash transaction.text. Valid algorithms: - SHA-256 - SHA-384 - SHA-512 |
| nonce | String | An arbitrary string that can be used just once in a cryptographic communication. Present only when the protocol is FIDO2. Nonce that the server used to derive the challenge used in the transaction. |
| serverChallenge | String | The initial server challenge. Present only when the protocol is FIDO2. Initial server challenge that the server used to derive the final challenge used in the transaction. |

For example:

```plaintext
"transactionResult": {
    "hash":"kXVq3Ci7isnZyLauHgWuJnBA6VkpWcqKOxxAXfKTnG8",
    "hashAlgorithm":"SHA-256",
    "nonce":"5EhnsUNuKgcUuLjHandE-w",
    "serverChallenge":"Bv2MqK_8tok5zWQW6rObREjJk-vg70-s5g9Rsvi4XVQ"
}
```

[FINISH_OOB_AUTH](/dpoa/docs/s3suite94-out-of-band-authentication#finishoobauth) returns TransactionResult as a part of the response payload when a transaction is performed.

## Uvm

Describes a user verification method. Contains parsed uvm details from the fido.uaf.uvm extension. It is returned as part of [AuthenticatorResult](/dpoa/docs/s3suite94-nok-nok-data-types#authenticatorresult) in the response from [FINISH_REG](/dpoa/docs/s3suite94-fido-registration#finishreg). Uvm contains the following attributes:

| **Name** | **Type** | **Description** |
| --- | --- | --- |
| keyProtection | String | Comma-separated description(s) of the key protection flag(s) that are received by the server. Valid descriptions: - software - hardware - TEE - secure_element - remote |
| matcherProtection | String | Comma-separated description(s) of the method(s) that the authenticator uses to protect its matcher that are received by the server. Valid descriptions: - software - tee - chip |
| userVerificationMethod | String | Comma-separated description(s) of the user verification method flag(s) that are received by the server. Valid descriptions: - presence_internal - fingerprint_internal - passcode_internal - voiceprint_internal - faceprint_internal - location_internal - eyeprint_internal - pattern_internal - handprint_internal - none - all |

The client app running on the second device calls INIT_OOB_AUTH when OOB authentication is performed during Adaptive Authentication.