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:
|
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>/regSample 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:
|
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:
|
4430 | User not found exception | User doesn't exist on the Server. |
Samples
Sample Request URL
https://www.example.com:8443/nnlgateway/nnl/<tenantID>/regSample 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:
|
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:
|
4430 | User not found exception | User doesn't exist on the Server. |
Samples
Sample Request URL
https://www.example.com:8443/nnlgateway/nnl/<tenantID>/regSample 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:
|
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:
|
4430 | User not found exception | User doesn't exist on the Server. |
Samples
Sample Request URL
https://www.example.com:8443/nnlgateway/nnl/<tenantID>/regSample 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>"
}