URL: /nnlgateway/nnl/<tenantID>/reg Method: POST |
Digipass S3 Authentication Software provides operations under the /nnl/v2/reg endpoint to register non-FIDO authentication methods like Email OTP, SMS OTP, and Photo ID. Using these operations you can initiate registration, complete registration, and cancel registration. To register FIDO authentication methods, use the API calls in section FIDO Registration.
The following operations are available:
INIT_SETUP
Initiates registration of a non-FIDO authentication method (OTP and Photo ID) for Adaptive Authentication. For FIDO methods use INIT_REG.
INIT_SETUP expects to receive data specific to the non-FIDO authentication method in the method.data request attribute.
Email OTP: The user's email address that receives the verification code.
"data": {"identifier": "user@noknok.com"}SMS OTP: The user's phone number that receives the verification code.
"data": {"identifier": "+18005551234"}Photo ID: The scan reference ID to get the results of facial recognition.
"data":{
"scanReferenceId": "c2f59eae-8404-4db5-8338-18ac42439eb7"
}See About Photo ID for an explanation of scan reference ID.
For more details about method.data, see Data Field Contents by Authentication Method.
Request
Attribute | Description |
|---|---|
operation | Required. The string INIT_SETUP |
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 a FIDO operation, like registration. An alphanumeric string, maximum of 255 characters. No special characters are allowed. If not provided, the Server generates a new ID and returns it in the response. |
locale | Optional. The Server uses locale, in subsequent calls to email OTP and SMS OTP, 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. |
message | Optional. Generated by the App SDK on the client. This is an opaque value. The client app is responsible for sending message. This is a base64-URL encoded string. |
method | Required. The authentication method being registered. Method. INIT_SETUP expects you to assign specific information to method.data. See the description for INIT_SETUP above |
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 | Used to correlate 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. |
method | The result information about the method the user is attempting to register. Method. Check the following fields in Method for results:
|
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 attribute is present in the response upon a successful operation (Server status of 4000).
Attribute | Description |
|---|---|
username | The name of the user who is registering. String. |
Response Status Codes
The following are the descriptions of the Auth Server status codes returned by INIT_SETUP. 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 | The method has been processed and completed.
|
4005 | Operation in progress. | When the processed method result is in pending state. For example, for Email OTP and SMS OTP the state is AWAITING_USER_ACTION and for Photo ID the state is PENDING. |
4402 | Security Exception | An invalid method name or statusHandle was provided in the request. |
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 request | One or more of the following mandatory attributes is missing:
|
4408 | Unsupported client message exception | Invalid message attribute. The client does not support the UAF/FIDO2 protocol. Or protocol information is missing. |
4409 | Client message exception | The message attribute is invalid (for example, there was a JSON syntax error). The message attribute from the App SDK is malformed (base64URL decode failed). |
4454 | Operation failed. | When method processing fails with an error code. |
Samples
Sample Request URL
https://www.example.com:8443/nnlgateway/nnl/<tenantID>/regSample Email OTP Request
{
"operation":"INIT_SETUP",
"sessionData":{
"sessionKey":"<session JWT>"
},
"message":"<base64url-encoded-data>",
"method":{
"name":"OTP Using Email",
"type":"Email OTP",
"data":{
"identifier":"user@noknok.com"
}
}
}Sample Photo ID Request
{
"operation":"INIT_SETUP",
"sessionData":{
"sessionKey":"<session JWT>"
},
"message":"<base64url-encoded-data>",
"method":{
"name":"Using Photo ID",
"type":"Photo ID",
"data":{
"scanReferenceId":"c2f59eae-8404-4db5-8338-18ac42439eb7"
}
}
}Sample SMS OTP Request
{
"operation":"INIT_SETUP",
"sessionData":{
"sessionKey":"<session JWT>"
},
"message":"<base64url-encoded-data>",
"method":{
"name":"OTP Using SMS",
"type":"SMS OTP",
"data":{
"identifier":"+18885559876"
}
}
}Sample Email OTP Response
{
"userName":"zsmith@noknok.com",
"statusCode":4005,
"method":{
"lifetimeMillis":598637,
"statusHandle":"a2V5aGFuZGxlAAAAAkJimA6d-mU-F34FVXt0OUXEWo0jkSZ6DytGEtKa3f6z4CNOnPIjaztJ0EMRyfZJ7QdIn1ASJXrvtdM3hugycA",
"data":{
"identifier":"user@noknok.com",
"additionalInfo":{
"device":{
"id":"123456789abcdef1234567890",
"type":"android",
"info":"OneSpan's device",
"model":"Galaxy S20",
"os":"Android 12",
"manufacturer":"Samsung"
},
"app":{
"id":"com.noknok.android.onramp",
"name":"OnRamp"
},
"extensions":[
{
"id":"noknok.uaf.location",
"data":"{\"status\":0,\"latitude\":37.46,\"longitude\":-122.143,\"accuracy\":99.2,\"countryCode\":\"US\"}",
"operation":"INIT_ADAPTIVE"
}
]
}
},
"name":"OTP Using Email",
"state":"AWAITING_USER_ACTION",
"type":"Email OTP"
},
"id":"nXikwIKiffYQLXAfGKjUBQ"
}Sample Photo ID Response
{
"userName":"zsmith@noknok.com",
"statusCode":4005,
"method":{
"statusHandle":"8iXuxwnpNfGrTLy61UE4lH7NmS4oV1vNEcVF6tKUhgA",
"name":"Using Photo ID",
"state":"PENDING",
"type":"Photo ID",
"data":{
"additionalInfo":{
"device":{
"id":"123456789abcdef1234567890",
"type":"android",
"info":"OneSpan's device",
"model":"Galaxy S20",
"os":"Android 12",
"manufacturer":"Samsung"
},
"app":{
"id":"com.noknok.android.onramp",
"name":"OnRamp"
},
"extensions":[
{
"id":"noknok.uaf.location",
"data":"{\"status\":0,\"latitude\":37.46,\"longitude\":-122.143,\"accuracy\":99.2,\"countryCode\":\"US\"}",
"operation":"INIT_ADAPTIVE"
}
]
}
}
},
"id":"XfqjEwauMZoDq9bI7NRN1g"
}Sample SMS OTP Response
{
"userName":"zsmith@noknok.com",
"statusCode":4005,
"method":{
"lifetimeMillis":599310,
"statusHandle":"6aMH58EssGoXSsaHx5w4UGfp0JTzwitUU0VmgM9kehY",
"data":{
"identifier":"+18885559876",
"additionalInfo":{
"device":{
"id":"123456789abcdef1234567890",
"type":"android",
"info":"OneSpan's device",
"model":"Galaxy S20",
"os":"Android 12",
"manufacturer":"Samsung"
},
"app":{
"id":"com.noknok.android.onramp",
"name":"OnRamp"
},
"extensions":[
{
"id":"noknok.uaf.location",
"data":"{\"status\":0,\"latitude\":37.46,\"longitude\":-122.143,\"accuracy\":99.2,\"countryCode\":\"US\"}",
"operation":"INIT_ADAPTIVE"
}
]
}
},
"name":"OTP Using SMS",
"state":"AWAITING_USER_ACTION",
"type":"SMS OTP"
},
"id":"p6C-jlke9o15dd7azWNTtA"
}SETUP
Completes registration using the provided authentication method. If Method is not provided, checks and returns the status of registration.
Request
Attribute | Description |
|---|---|
operation | Required. The string SETUP |
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. |
locale | Optional. The Server uses locale, in subsequent calls to email OTP and SMS OTP, 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. |
method | Required. Data about the authentication method being registered. Method. Assign the one-time passcode to method.data.otp for
|
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. |
method | Result of registering the authentication method. Method. Check the following fields in Method for results:
|
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 attribute is present in the response upon a successful operation (Server status of 4000).
Attribute | Description |
|---|---|
username | The user who is registering. username must be unique across all users in a tenant. String. |
additionalInfo | An object containing information from the client app. In order for the API Server to return this information, the client app must have sent this information in the INIT_SETUP request message attribute. In addition, the Server's response filter must be configured to return app information and payload extensions. By default, the API Server automatically returns device information. Refer to Response Filter Configuration. This object contains 3 attributes:
|
Response Status Codes
The following are the descriptions of the Auth Server status codes returned by SETUP. 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 | The authentication method was successfully setup. |
4005 | Operation in progress. | When the processed method result is in pending state. For example, for Email OTP and SMS OTP the state is AWAITING_USER_ACTION and for Photo ID the state is PENDING. |
4402 | Security Exception | An invalid method name or statusHandle was provided in the request. |
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 request | One or more of the following mandatory attributes is missing:
|
4454 | Operation failed. | When the method processing fails with an errorCode. |
Samples
Sample Request URL
https://www.example.com:8443/nnlgateway/nnl/<tenantID>/regSample Request for Email OTP
{
"operation": "SETUP",
"sessionData": {
"sessionKey": "<session JWT>"
}
"method": {
"name": "OTP Using Email",
"type": "Email OTP",
"data": {
"otp": "82137"
},
"statusHandle": "8wR9Xxd49yXhaXS4guJvyYE-xNRZ2RMhlDbRJ4fvWr8"
}
}Sample Request for SMS OTP
{
"operation":"SETUP",
"sessionData": {
"sessionKey": "<session JWT>"
},
"id":"1234",
"method":{
"name":"OTP Using SMS",
"type":"SMS OTP",
"data":{
"otp":"397156"
},
"statusHandle":"dtgtUrcjc6erZsaW67cwCzRo8GYRYYBU1aDXTRJzYtY"
}
}Sample Request for Photo ID
{
"operation": "SETUP",
"sessionData": {
"sessionKey": "<session JWT>"
},
"method": {
"statusHandle": "nAWKptEV5YxObRuDbJ8mFFnSyok6hS_15UaEmq7uEYA",
"name": "Using Photo ID",
"type": "Photo ID"
}
}Sample Response for Email OTP
{
"userName":"zsmith@noknok.com",
"statusCode":4000,
"method":{
"statusHandle":"8wR9Xxd49yXhaXS4guJvyYE-xNRZ2RMhlDbRJ4fvWr8",
"data":{
"identifier":"zsmith@noknok.com"
},
"name":"OTP Using Email",
"state":"SUCCEEDED",
"type":"Email OTP"
},
"id":"fj1sfGttiTmVxEhiUi6VRQ"
}Sample Response for SMS OTP
{
"userName":"zsmith@noknok.com",
"statusCode":4000,
"method":{
"statusHandle":"dtgtUrcjc6erZsaW67cwCzRo8GYRYYBU1aDXTRJzYtY",
"data":{
"identifier":"+14155551212"
},
"name":"OTP Using SMS",
"state":"SUCCEEDED",
"type":"SMS OTP"
},
"id":"Q6u-DYoeoDjRfCYbDFrNrg"
}Sample Response for Photo ID
{
"userName":"zsmith@noknok.com",
"statusCode":4000,
"method":{
"type":"Photo ID",
"name":"Using Photo ID",
"state":"SUCCEEDED",
"data":{
"identifier":"ID_CARD:Rlm8AbcI4B8sKT_lCAyTyTFpQY9R6aTNZ3qzx3830dQ"
},
"statusHandle":"a2V5aGFuZGxlAAAAAkVwHMRe8oU4rt6Ww--CW3lz4NxqW9dyiF7AwYkUKXkCDm3uot2jj0Yq8PlsFxpK7XBJVaETwNJjD3Xz0hvDiYVcXvZfLF-3cLeuJhv9"
}
}CANCEL_SETUP
Cancels the registration of the specified non-FIDO authentication method.
Request
Attribute | Description |
|---|---|
operation | Required. The string CANCEL_SETUP. |
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. |
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. |
method | Required. The method whose registration is being cancelled. 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. |
method | You can find return information about the cancelled authentication method. Method. Check the state field in Method for results. |
statusCode | Server-specific status code that reports the success or failure of this operation. Integer. |
The following attribute is present in the response upon a successful operation (Server status of 4000).
Attribute | Description |
|---|---|
username | The user who is cancelling registration. String. |
Response Status Codes
The following are the descriptions of the Auth Server status codes returned by CANCEL_SETUP. 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 | Request has been created successfully. |
4401 | Operation expired | Sent when the operation has expired for a particular statusHandle. |
4402 | Security exception | Occurs when the wrong value was entered for following fields
|
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 request | One or more of the following mandatory attributes is missing:
|
Samples
Sample Request URL
https://www.example.com:8443/nnlgateway/nnl/<tenantID>/regSample Email OTP Request
{
"operation": "CANCEL_SETUP",
"sessionData": {
"sessionKey": "<session JWT>"
},
"method": {
"name": "OTP Using Email",
"type": "Email OTP",
"statusHandle": "EX6m3BXHtGnf7055WDzhsecLbOUIQ5UmD7PDndMs7mI"
}
}Sample Email OTP Response
{
"userName":"zsmith@noknok.com",
"statusCode":4000,
"method":{
"statusHandle":"EX6m3BXHtGnf7055WDzhsecLbOUIQ5UmD7PDndMs7mI",
"data":{
"identifier":"user@noknok.com"
},
"name":"OTP Using Email",
"state":"CANCELLED",
"type":"Email OTP"
},
"id":"ghi0xh1nuJr00Jh8Kh_Zrw"
}