Digipass S3 is now DigipassONE. This section is currently being updated to reflect our new name.

Manage non-FIDO registrations

Prev Next

URL: /nnlgateway/nnl/<tenantID>/reg Method: POST


Digipass S3 Authentication Software provides operations to manage non-FIDO authentication methods like Email OTP, SMS OTP, Photo ID, and External Authentication. Using these operations you can retrieve a user's non-FIDO methods, delete their registered non-FIDO methods, suspend their non-FIDO methods, and resume any suspended methods. To manage FIDO authentication methods, use the operations, see Manage FIDO Registrations.

The following operations are available:

LIST_METHODS

Lists registered non-FIDO authentication method(s) for a user.

Request

Attribute

Description

operation

Required. The string LIST_METHODS.

callerOrigin

Required if a web app is sending the request and that app has a different origin than the Digipass S3 API Server. A web origin is defined by the scheme (protocol), host (domain), and port of the URL used to access it.

The API Server checks if this origin is listed in its origin allow list, if not, the request is rejected. See My Web Apps Have a Different Origin.

id

Optional. The correlation ID, a unique id that ties together different requests that comprise an operation. Alphanumeric string with a maximum length of 255 characters. No special characters are allowed.

If not provided, the Server generates a unique id and returns it.

locale

Optional. The Server uses locale to tailor the end user's prompts to the language in the user’s profile. An IETF BCP 47 language tag string, like en-US.

sessionData

Required. An object containing the user's session information, may include the user name. See SessionData.

Response

The following attributes are always present in the JSON payload of the response.

Attribute

Description

id

The unique id that correlates different requests comprising an operation. A Base64-URL encoded string.

If id was sent in the request, the same id is returned. If not, a server-generated ID is returned. If id was provided in the REST payload but the server was unable to parse the payload, the value is unknown.

statusCode

Server-specific status code that reports the success or failure of this operation. Integer.

See Response Status Codes below for the status and error codes.

The following attributes are present in the response upon a successful operation (Server status of 4000).

Attribute

Description

methods

A list of authentication methods objects that are registered to the user. Set<Authentication Method>. The two fields listed in the rows below are of special note.

The server returns a different set of fields under methods.data, depending on the type of authentication method. For example, Photo ID has a different set of fields than SMS OTP. For details, see Data Field Contents by Authentication Method.

methods.data.identifier

Present when the authentication method is Email OTP, External Authentication, Photo ID, or SMS OTP. Has the following value:

  • Email OTP: user's email address that receives the passcode

  • External Auth: user name

  • Photo ID: ID type and hash of the content which could have come from an identification document such as a driver's license or passport.

  • SMS OTP: user's phone number that receives the passcode

methods.data.devices

Present for all non-FIDO authentication methods. Contains information about the devices where the method was registered.

methods.data.lastUsedTimeStamp

The time when the authentication method was last used.

Response Status Codes

The following are the descriptions of the Auth Server status codes returned by LIST_METHODS. Under certain circumstances, the API Server returns an unsuccessful HTTP status code. Examples include an invalid request or invalid session. You can find descriptions of these in API Server Status Codes.

Server Status Code

Description

Examples

4000

Ok. Operation completed.

Methods for the specified user were successfully fetched.

4402

Security exception

The facet ID sent by the client doesn't match the valid facet IDs configured on the Authentication Server.

4404

Internal Server error

Internal server error.

Failed to read from the database.

Failed to connect to the database.

Failed to read required properties.

4406

Unacceptable content in the request.

One or more mandatory attributes are missing.

4430

User not found exception

User doesn't exist in the Server.

Sample

Sample Request URL

https://www.example.com:8443/nnlgateway/nnl/<tenantID>/reg

Sample Request

{
  "operation": "LIST_METHODS",
  "id":"any id",
  "sessionData": {
        "sessionKey": "<session JWT>"
    }
}

Sample Response

new fields added in this release are highlighted below.

{
  "statusCode":4000,
  "methods":[
    {
      "name":"Using Photo ID",
      "type":"Photo ID",
      "data":{
        "identifier":"ID_CARD:vdEAcb6OYnS4vFxChEA50kvn4xthGvmLDAMkJIf7cgY",
        "status":1,
        "devices":[
          {
            "device":{
              "id":"f307c6bd-deec-4609-83fd-0b5494d6c31c",
              "deviceType":"browser",
              "info":"Brave on macOS",
              "os":"macOS 13.5.0"
            },
            "app":{
              "id":"https://example.noknoktest.com",
              "name":"https://example.noknoktest.com/gwtutorial/",
              "qrSupported":true
            }
          }
        ]
      }
    },
    {
      "name":"OTP Using SMS",
      "type":"SMS OTP",
      "data":{
        "identifier":"+14155551212",
        "status":1,
        "devices":[
          {
            "device":{
              "id":"123456789abcdef1234567890",
              "deviceType":"android",
              "info":"Jane Pixel 6a
              "model":"Pixel 6a",
              "os":"Android 14",
              "manufacturer":"Google",
              "push":{
                "pushHandleString":"a2V5aGFuZGxlAAAAAahLsSiuNgWYfnKliqKlsoKJHeeZWd1N-kOuT_SjvCSxu9P9q8e0MMS3zY8VLepzPBZcRC1vqd2T6iJu3WFgUxuzw63rRPTQYbjB8TLhz_OVi4Z1KNOsgm_tPPF0aQZc2masSx8zkRa6UdxT7DisQm_dHdKRcl-BRGmTxQ",
                "handleLifetimeDays":30,
                "createdTimeStamp":"2024-02-02T08:10:22.969Z"
              }
            },
            "app":{
              "id":"android:apk-key-hash:rDQ4Tn60fAvxP8thtp6sOh5ococ",
              "name":"android:com.noknok.test.client",
              "qrSupported":true
            }
          },
          {
            "device":{
              "id":"f307c6bd-deec-4609-83fd-0b5494d6c31c",
              "deviceType":"browser",
              "info":"Brave on macOS",
              "os":"macOS 13.5.0"
            },
            "app":{
              "id":"https://example.noknoktest.com",
              "name":"https://example.noknoktest.com/gwtutorial/",
              "qrSupported":true
            }
          }
        ]
      }
    },
    {
      "name":"OTP Using Email",
      "type":"Email OTP",
      "data":{
        "identifier":"user@noknok.com",
        "status":1,
        "devices":[
          {
            "device":{
              "id":"New Device",
              "deviceType":"android",
              "info":"NokNok Emulator",
              "model":"NokNok-AE 7.0",
              "os":"NokNokOS 7.0",
              "manufacturer":"NokNok"
            },
            "app":{
              "id":"android:apk-key-hash:rDQ4Tn60fAvxP8thtp6sOh5ococ",
              "name":"android:com.noknok.test.client",
              "qrSupported":true
            }
          },
          {
            "device":{
              "id":"123456789abcdef1234567890",
              "deviceType":"android",
              "info":"NokNok Emulator",
              "model":"NokNok-AE 7.0",
              "os":"NokNokOS 7.0",
              "manufacturer":"NokNok",
              "push":{
                "pushHandleString":"a2V5aGFuZGxlAAAAAahLsSiuNgWYfnKliqKlsoKJHeeZWd1N-kOuT_SjvCSxu9P9q8e0MMS3zY8VLepzPBZcRC1vqd2T6iJu3WFgUxuzw63rRPTQYbjB8TLhz_OVi4Z1KNOsgm_tPPF0aQZc2masSx8zkRa6UdxT7DisQm_dHdKRcl-BRGmTxQ",
                "handleLifetimeDays":30,
                "createdTimeStamp":"2024-02-02T08:10:22.969Z"
              }
            },
            "app":{
              "id":"android:apk-key-hash:rDQ4Tn60fAvxP8thtp6sOh5ococ",
              "name":"android:com.noknok.test.client",
              "qrSupported":true
            }
          },
          {
            "device":{
              "id":"f307c6bd-deec-4609-83fd-0b5494d6c31c",
              "deviceType":"browser",
              "info":"Brave on macOS",
              "os":"macOS 13.5.0"
            },
            "app":{
              "id":"https://example.noknoktest.com",
              "name":"https://example.noknoktest.com/gwtutorial/",
              "qrSupported":true
            }
          }
        ]
      }
    }
  ],
  "id":"any id"
}

DELETE_METHODS

Deletes the specified non-FIDO authentication methods for a user.

Request

Attribute

Description

operation

Required.The string DELETE_METHODS.

callerOrigin

Required if a web app is sending the request and that app has a different origin than the Digipass S3 API Server. A web origin is defined by the scheme (protocol), host (domain), and port of the URL used to access it.

The API Server checks if this origin is listed in its origin allow list, if not, the request is rejected. See My Web Apps Have a Different Origin.

id

Optional. The correlation ID, a unique id that ties together different requests that comprise an operation. Alphanumeric string with a maximum length of 255 characters. No special characters are allowed.

If not provided, the Server generates a unique id and returns it.

locale

Optional. The Server uses locale to tailor the end user's prompts to the language in the user’s profile. An IETF BCP 47 language tag string, like en-US.

methods

Required. The operation deletes these authentication methods for the user. Set<Authentication Method>.

sessionData

Required. An object containing the user's session information, may include the user name. See SessionData.

Response

The following attributes are always present in the JSON payload of the response.

Attribute

Description

id

The unique id that correlates different requests comprising an operation. A Base64-URL encoded string.

If id is sent in the request, the same id is returned. If not, a server-generated ID is returned. If id was provided in the REST payload but the server was unable to parse the payload, the value is unknown.

statusCode

Server-specific status code that reports the success or failure of this operation. Integer.

See Response Status Codes below for the status and error codes.

The following attributes are present in the response upon a successful operation (Server status of 4000).

Attribute

Description

methods

A list of authentication methods objects that were deleted for the user. Set<Authentication Method>. The two fields listed in the rows below are of special note.

The server returns a different set of fields under methods.data, depending on the type of authentication method. For example, Photo ID has a different set of fields than SMS OTP. For details, see Data Field Contents by Authentication Method.

methods.data.identifier

Present when the authentication method is Email OTP, External Authentication, Photo ID, or SMS OTP. Has the following value:

  • Email OTP: user's email address that receives the passcode

  • External Auth: user name

  • Photo ID: ID type and hash of the content which could have come from an identification document such as a driver's license or passport.

  • SMS OTP: user's phone number that receives the passcode

methods.data.devices

Present for all non-FIDO authentication methods. Contains information about the devices where the method was either registered or used to verify the user.

Response Status Codes

The following are the descriptions of the Auth Server status codes returned by DELETE_METHODS. Under certain circumstances, the API Server returns an unsuccessful HTTP status code. Examples include an invalid request or invalid session. You can find descriptions of these in API Server Status Codes.

Server Status Code

Description

Examples

4000

Ok. Operation completed.

Authentication methods for the specified user were successfully deleted.

4402

Security exception

The facet ID sent by the client doesn't match the valid facet IDs configured on the Authentication Server.

4404

Internal Server error

Internal server error.

Failed to read from the database.

Failed to connect to the database.

Failed to read required properties.

4406

Unacceptable content in the request.

One or more of the following mandatory attributes is missing from the request:

  • sessionData

  • methods

4430

User not found exception

User doesn't exist on the Server.

Samples

Sample Request URL

https://www.example.com:8443/nnlgateway/nnl/<tenantID>/reg

Sample Request

The following block represents a sample request for deleting Email OTP method for a user.

{
    "operation":"DELETE_METHODS",
    "sessionData":{
        "sessionKey":"<session JWT>"
    },
    "id":"<sample_correlation_id>",
    "methods":[
        {
            "name":"OTP Using Email",
            "type":"Email OTP",
            "data":{
                "identifier":"user@noknok.com"
            }
        }
    ]
}

Sample Response

{
  "statusCode":4000,
  "methods":[
    {
      "name":"OTP Using Email",
      "type":"Email OTP",
      "data":{
        "identifier":"user@noknok.com",
        "devices":[
          {
            "device":{
              "id":"68C3C6F9-1F12-4584-99BD-A43AC129A349",
              "deviceType":"ios",
              "info":"iPhone",
              "model":"iPhone12,3",
              "os":"iOS 16.6.1",
              "manufacturer":"Apple",
              "push":{
                "handleLifetimeDays":30,
                "createdTimeStamp":"2024-01-03T08:54:00.393Z",
                "pushHandle":"a2V5aGFuZGxlAAAAAjN9N3exDUlrhpvi333ab-CeRb3AVkaWVe_3ZqzEu6NYGqv7Xb9AoxrVhFag-z5VzCW7ALvAnlA1SskqKMeEbR73-Wkon-GcteAq8mj1ifqnj_XEIvayaUzi-AGEK0yu9xObP0Fzqfv4fBIti_fx5PlZ_2GkZk543RJ6vPwTEfLIyAKUTUSj"
              }
            },
            "app":{
              "id":"ios:bundle-id:com.noknok.ios.tutorialappplus",
              "name":"ios:com.noknok.ios.tutorialappplus",
              "qrSupported":true
            }
          }
        ]
      }
    }
  ],
  "id":"<sample_correlation_id>"
}

SUSPEND_METHODS

Suspends the specified non-FIDO authentication methods for a user.

Request

Attribute

Description

operation

Required.The string SUSPEND_METHODS.

callerOrigin

Required if a web app is sending the request and that app has a different origin than the Digipass S3 API Server. A web origin is defined by the scheme (protocol), host (domain), and port of the URL used to access it.

The API Server checks if this origin is listed in its origin allow list, if not, the request is rejected. See My Web Apps Have a Different Origin.

id

Optional. The correlation ID, a unique id that ties together different requests that comprise an operation. Alphanumeric string with a maximum length of 255 characters. No special characters are allowed.

If not provided, the Server generates a unique id and returns it.

locale

Optional. The Server uses locale to tailor the end user's prompts to the language in the user’s profile. An IETF BCP 47 language tag string, like en-US.

methods

Required. The operation suspends the provided authentication methods for the user. Set<AuthenticationMethodss>.

sessionData

Required. An object containing the user's session information. See SessionData.

Response

The following attributes are always present in the JSON payload of the response.

Attribute

Description

id

The unique id that correlates different requests comprising an operation. A Base64-URL encoded string.

If id was sent in the request, the same id is returned. If not, a server-generated ID is returned. If id was provided in the REST payload but the server was unable to parse the payload, the value is unknown.

statusCode

Server-specific status code that reports the success or failure of this operation. Integer.

See Response Status Codes below for the status and error codes.

The following attributes are present in the response upon a successful operation (Server status of 4000).

Attribute

Description

methods

A list of authentication methods objects that were suspended for the user. Set<AuthenticationMethod>. The two fields listed in the rows below are of special note.

The server returns a different set of fields under methods.data, depending on the type of authentication method. For example, Photo ID has a different set of fields than SMS OTP. For details, see Data Field Contents by Authentication Method.

methods.data.identifier

Present when the authentication method is Email OTP, External Authentication, Photo ID, or SMS OTP. Has the following value:

  • Email OTP: user's email address that receives the passcode

  • External Auth: user name

  • Photo ID: ID type and hash of the content which could have come from an identification document such as a driver's license or passport.

  • SMS OTP: user's phone number that receives the passcode

methods.data.devices

Present for all non-FIDO authentication methods. Contains information about the devices where the method was either registered or used to verify the user.

Response Status Codes

The following are the descriptions of the Auth Server status codes returned by SUSPEND_METHODS. Under certain circumstances, the API Server returns an unsuccessful HTTP status code. Examples include an invalid request or invalid session. You can find descriptions of these in API Server Status Codes.

Server Status Code

Description

Examples

4000

Ok. Operation completed.

Authentication methods for the specified user were successfully suspended.

4006

Ok. Operation completed successfully partially

Partial authentication methods for the specified user were successfully suspended, but few were not found.

4402

Security exception

The facet ID sent by the client doesn't match the valid facet IDs configured on the Authentication Server.

4404

Internal Server error

Internal server error.

Failed to read from the database.

Failed to connect to the database.

Failed to read required properties.

4406

Unacceptable content in the request.

One or more of the following mandatory attributes is missing from the request:

  • sessionData

  • methods

4430

User not found exception

User doesn't exist on the Server.

Samples

Sample Request URL

https://www.example.com:8443/nnlgateway/nnl/<tenantID>/reg

Sample Request

The following block represents a sample request for suspending Email OTP method for a user.

{
    "operation":"SUSPEND_METHODS",
    "sessionData":{
        "sessionKey":"<session JWT>"
    },
    "id":"<sample_correlation_id>",
    "methods":[
        {
            "name":"OTP Using Email",
            "type": "Email OTP",
            "data":{
                "identifier":"user@noknok.com"
            }
        }
    ]
}

Sample Response

{
  "statusCode":4000,
  "methods":[
    {
      "name":"OTP Using Email",
      "type":"Email OTP",
      "data":{
        "identifier":"user@noknok.com",
        "devices":[
          {
            "device":{
              "id":"68C3C6F9-1F12-4584-99BD-A43AC129A349",
              "deviceType":"ios",
              "info":"iPhone",
              "model":"iPhone12,3",
              "os":"iOS 16.6.1",
              "manufacturer":"Apple",
              "push":{
                "handleLifetimeDays":30,
                "createdTimeStamp":"2024-01-03T08:54:00.393Z",
                "pushHandle":"a2V5aGFuZGxlAAAAAjN9N3exDUlrhpvi333ab-CeRb3AVkaWVe_3ZqzEu6NYGqv7Xb9AoxrVhFag-z5VzCW7ALvAnlA1SskqKMeEbR73-Wkon-GcteAq8mj1ifqnj_XEIvayaUzi-AGEK0yu9xObP0Fzqfv4fBIti_fx5PlZ_2GkZk543RJ6vPwTEfLIyAKUTUSj"
              }
            },
            "app":{
              "id":"ios:bundle-id:com.noknok.ios.tutorialappplus",
              "name":"ios:com.noknok.ios.tutorialappplus",
              "qrSupported":true
            }
          }
        ]
      }
    }
  ],
  "id":"<sample_correlation_id>"
}

RESUME_METHODS

Resumes the specified non-FIDO authentication methods for a user.

Request

Attribute

Description

operation

Required.The string RESUME_METHODS.

callerOrigin

Required if a web app is sending the request and that app has a different origin than the Digipass S3 API Server. A web origin is defined by the scheme (protocol), host (domain), and port of the URL used to access it.

The API Server checks if this origin is listed in its origin allow list, if not, the request is rejected. See My Web Apps have a Different Origin.

id

Optional. The correlation ID, a unique id that ties together different requests that comprise an operation. Alphanumeric string with a maximum length of 255 characters. No special characters are allowed.

If not provided, the Server generates a unique id and returns it.

locale

Optional. The Server uses locale to tailor the end user's prompts to the language in the user’s profile. An IETF BCP 47 language tag string, like en-US.

methods

Required. The operation resumes the provided authentication methods for the user. Set<Authentication Method>.

sessionData

Required. An object containing the user's session information. See SessionData.

Response

The following attributes are always present in the JSON payload of the response.

Attribute

Description

id

The unique id that correlates different requests comprising an operation. A Base64-URL encoded string.

If id was sent in the request, the same id is returned. If not, a server-generated ID is returned. If id was provided in the REST payload but the server was unable to parse the payload, the value is unknown.

statusCode

Server-specific status code that reports the success or failure of this operation. Integer.

See Response Status Codes below for the status and error codes.

The following attributes are present in the response upon a successful operation (Server status of 4000).

Attribute

Description

methods

A list of authentication methods objects that were resumed for the user. Set<Authentication Method>. The two fields listed in the rows below are of special note.

The server returns a different set of fields under methods.data, depending on the type of authentication method. For example, Photo ID has a different set of fields than SMS OTP. For details, see Data Field Contents by Authentication Method.

methods.data.identifier

Present when the authentication method is Email OTP, External Authentication, Photo ID, or SMS OTP. Has the following value:

  • Email OTP: user's email address that receives the passcode

  • External Auth: user name

  • Photo ID: ID type and hash of the content which could have come from an identification document such as a driver's license or passport.

  • SMS OTP: user's phone number that receives the passcode

methods.data.devices

Present for all non-FIDO authentication methods. Contains information about the devices where the method was either registered or used to verify the user.

Response Status Codes

The following are the descriptions of the Auth Server status codes returned by RESUME_METHODS. Under certain circumstances, the API Server returns an unsuccessful HTTP status code. Examples include an invalid request or invalid session. You can find descriptions of these in API Server Status Codes.

Server Status Code

Description

Examples

4000

Ok. Operation completed.

Authentication methods for the specified user were successfully resumed.

4006

Ok. Operation completed successfully partially

Partial authentication methods for the specified user were successfully resumed, but few were not found.

4402

Security exception

The facet ID sent by the client doesn't match the valid facet IDs configured on the Authentication Server.

4404

Internal Server error

Internal server error.

Failed to read from the database.

Failed to connect to the database.

Failed to read required properties.

4406

Unacceptable content in the request.

One or more of the following mandatory attributes is missing from the request:

  • sessionData

  • methods

4430

User not found exception

User doesn't exist on the Server.

Samples

Sample Request URL

https://www.example.com:8443/nnlgateway/nnl/<tenantID>/reg

Sample Request

The following block represents a sample request for resuming Email OTP method for a user.

{
    "operation":"RESUME_METHODS",
    "sessionData":{
        "sessionKey":"<session JWT>"
    },
    "id":"<sample_correlation_id>",
    "methods":[
        {
            "name":"OTP Using Email",
            "type":"Email OTP",
            "data":{
                "identifier":"user@noknok.com"
            }
        }
    ]
}

Sample Response

{
  "statusCode":4000,
  "methods":[
    {
      "name":"OTP Using Email",
      "type":"Email OTP",
      "data":{
        "identifier":"user@noknok.com",
        "devices":[
          {
            "device":{
              "id":"68C3C6F9-1F12-4584-99BD-A43AC129A349",
              "deviceType":"ios",
              "info":"iPhone",
              "model":"iPhone12,3",
              "os":"iOS 16.6.1",
              "manufacturer":"Apple",
              "push":{
                "handleLifetimeDays":30,
                "createdTimeStamp":"2024-01-03T08:54:00.393Z",
                "pushHandle":"a2V5aGFuZGxlAAAAAjN9N3exDUlrhpvi333ab-CeRb3AVkaWVe_3ZqzEu6NYGqv7Xb9AoxrVhFag-z5VzCW7ALvAnlA1SskqKMeEbR73-Wkon-GcteAq8mj1ifqnj_XEIvayaUzi-AGEK0yu9xObP0Fzqfv4fBIti_fx5PlZ_2GkZk543RJ6vPwTEfLIyAKUTUSj"
              }
            },
            "app":{
              "id":"ios:bundle-id:com.noknok.ios.tutorialappplus",
              "name":"ios:com.noknok.ios.tutorialappplus",
              "qrSupported":true
            }
          }
        ]
      }
    }
  ],
  "id":"<sample_correlation_id>"
}