API Getting Started

Windows Communication Foundation (WCF) Services

In a .Net environment (Visual Studio 2005, - Visual Studio 2015) you can access the SAS WCF services by adding a service reference to your project. The service reference should be to the following endpoint:

https://sandbox.surepassid.com/AuthServerWCFService/SurePassAuthServerWCFService.svc

When you create the service reference Visual Studio will create a proxy class to the SAS service that makes accessing the server very easy hiding the complexity of web service Soap messages. This proxy class will contain all the methods that are supported by the SAS server. Each method in the proxy class maps directly to the same methods in the Rest/Json interface.

REST Interface

The REST interface provides a simple and easy RESTful interface to the MFAS services. This interface is recommended for integrating the MFAS services into the following applications:

PHP apps
Python apps
.net apps
Java apps
any server based app that supports REST

The format of the REST requests are:

http POST to:

https://server/AuthServer/REST/U2F/U2FServer.aspx

where server is:

sandbox.surepassid.com – SurePassID sandbox installation
cloud.surepassid.com - SurePassID production installation
other – on-premesis SurePassID installation

The REST request body is a json structure that specifies the type of action to be performed. All requests have the following common parameters:

'type' – The type of request to be performed by the server. The following types are supported.
'username' – The username (or token for the user) that this action is to be performed on.
'spAccountLoginName' – Your SurePassId server account name
'spAccountLoginKey' – Your SurePassId server account key

You can get your SurePass account credentials (server account name and key) from the the portal. After logging in go to Settings and you will see the following page where the values are displayed.

The system supports the following request api functions:

type	description	operational area
add_u2f_account	add user account with U2F device to your SurepassId installation	user management
add_oath_account	add user account with Oath device to your SurepassId installation	user management
add_u2f_device	add a u2f 2fa device to a user account	device management
add_oath_device	add an oath 2fa device to user account	device management
validate_user	query user meta data/authenticate user name and password	user validation/authentication
find_device	query device meta data by serial number	device management
delete_key	delete a specific fido u2f security key from the users account	fido u2f key/origin management
delete_all_keys	delete all fido u2f security key from the users account	fido u2f key/origin management
validate_oath_otp	validate a dynamic pass code send to the user	validate Oath OTP
send_oath_otp	send a dynamic pass code send to the user	send Oath OTP
push_oath_otp	push authentication request to the user	push authentication
pre_enroll	fido - pre-enroll u2f key for an origin	fido u2f register step 1
enroll	fido - enroll a u2f key for an origin	fido u2f register step 2
pre_sign	fido - pre-sign process u2f key for an origin	fide u2f authentication step 1
sign	fido - authenticate a u2f key for an origin	fido u2f authentication step 2
create_session_token	create a session token for a particular user	mobile device state management
expire_session_token	expire (make unusable) a session token for a particular user	mobile device state management
is_session_token_valid	check to see if a session token is still valid for a particular user	mobile device state management
active_oath_device	activate an Oath device	device management
sync_oath_device	synchronize clock for Oath HOTP/TOTP device	device management

A sample REST request body is a json request and looks like this:

Rest/Json Request Example - Send Pass Code via SMS

{ 
  "type": "send_oath_otp",
  "username": "Manny",
  "spAccountLoginName": "accountname", 
  "spAccountLoginKey": "accountkey",
  "deliveryMethod": "sms"
}

The REST response body is a json structure. All responses have the following items at a minimum:

type - Echo of the type that was made on the request
errorCode – The numeric error code for the request. An errorCode of 0 signifies success.
errorMessage – The displayable error message for the request.

Rest/Json Response Example - Send Pass Code

{
  "type": "send_oath_otp",
  "errorCode": 0,
  "errorMessage": "OK"
}