Introduction
Use the REST API operations to communicate with the Digipass S3 API Server. If you are a client app developer, pull down the Develop menu and choose the appropriate Dev Guide for your platform to learn how your client app communicates with the Digipass S3 API Server. There are two use cases for the REST API:
You plan to implement a custom plugin on the API Server to handle or alter the request sent by the App SDK. You may also want the custom plugin to handle or alter the response from the API Server.
You are planning to implement your own custom proxy that your app communicates with, instead of having your app communicate directly with the API Server.
In either case, use these REST API articles to understand the requests, responses, data structures and status codes that you need to communicate with the API Server.
About the API Server
The API Server handles all communication between the App SDK and the Authentication Server. It supports both the FIDO UAF and Web Authentication (WebAuthn or FIDO2) protocols. It handles session management and manages FIDO policies. It functions as a gatekeeper on incoming requests and the amount of information that is returned from the Authentication Server to the App SDK.
The API Server provides robust, flexible authentication depending on the user's context. See Adaptive Rulesets for an explanation of Adaptive Rules, sequences, authentication methods, FIDO policies, PostOperation Checks, Supplemental Checks, and data used by adaptive rules. The REST API assumes that you are already familiar with that content. In addition, you must configure the Authentication Server and your client apps to use Adaptive Rulesets. Also see Configure Adaptive Rulesets.
The API Server can optionally
generate a transaction confirmation token
handle communication when your company server performs an external authentication method
package and return EMV 3DS Session data
trigger push notifications for OOB authentication
identify the client platform or browser for web apps
extract and send the IP address from the request header
enable FIDO2 and WebAuthn authentication where the username is known up front
About the REST API
HTTP Header Values
All API Server REST APIs share the following HTTP header values:
HTTP Header | Request | Response |
|---|---|---|
Content-Type | application/json;charset=UTF-8 | application/json |
Accept | application/json | N/A |
Multi-tenancy Support
The Digipass S3 API Server is designed to work in a multi-tenancy environment. The Digipass S3 API Server and its plugins have separate configurations for each tenant (see API Server Configuration.) The Digipass S3 API Server receives the tenant ID as part of the URL in HTTP requests. For REST API calls, the following URL format should be used:
For Reg endpoint: https://example.com/nnlgateway/nnl/<tenantID>/reg
For Auth endpoint: https://example.com/nnlgateway/nnl/<tenantID>/auth
If tenantID is not specified, the value of the default_tenant_id configuration property is used. See Server Properties.
The Digipass S3 API Server uses the tenant ID to load a tenant-specific configuration and passes the tenant ID to the plugins to allow them to load their tenant-specific configuration. It then passes the tenant ID to the Digipass S3 Server.
API Server Status Codes
HTTP Status Code | Description |
|---|---|
200 | The API Server received a valid response from the Authentication Server. To learn whether the REST API operation succeeded or failed, check the statusCode. Refer to section Response Status Codes for the specific REST API operation. |
400 | The API Server received a bad request from the Client. For example, the API Server was unable to parse the JSON payload. |
401 | Unauthorized. For example, the Client tried to register without a valid session. |
403 | Forbidden. For example, the RP Web App has a different origin than API Server and its origin is not added into the allow list. |
404 | The API Server could not find the resource requested from the Client. For example, the Client used an incorrect registration or authentication URL path. |
500 | Internal server error. For example, something unexpected happened in the API Server internally or while communicating with the Auth Server. |
If a session (sessionData) is not present in the request, the App SDK returns a bad (invalid) session error, for example:
On Android: BAD_SESSION from ResultType enum
On iOS: BAD_SESSION from FidoStatus enum
On Web (Javascript SDK): INVALID_SESSION from Outcome object
This does not affect the case when an invalid (for example, expired) session is present in the request. In this case, App SDK returns a bad (invalid) session.
Authentication Methods
The following table shows the categories of authentication methods, together with the section where the applicable REST API operations are documented.
Category | Description | Examples | Section documenting registration operations | Section documenting authentication operations | Section documenting credential management operations |
|---|---|---|---|---|---|
FIDO | Includes UAF and FIDO2 | platform authenticator (e.g. Touch ID, Face ID), passcode, passkey, OOB using push and QR | |||
FIDO OOB | UAF or FIDO2 authentication takes place on the second device. | push and QR code | |||
Non-FIDO | Anything other than FIDO | external authentication (e.g. password), Email OTP, SMS OTP, Photo ID |