This document describes the list of Web Services forming inWebo authentication API. The SOAP API is described by the following WSDL files: Provisioning.wsdl used for user management requests.

Access to inWebo API is 2-factor secured. Configuration is done in inWebo Administration Console:

  • Restrict authorized IP addresses allowed to submit SOAP requests

  • Implement SSL client certificate authentication

Note

the Activation Code was formerly called "Secure Site ID" in some authentication tools or in the documentation.
Please note that a "Secure Site ID" refers to an activation code.


User management with SOAP API

(warning) Important notice : for all the following provisionning requests, the 'userid' parameter must be forced to 0.

Input parameters marked with * are mandatory.

loginsQuery

loginsQuery(long userid*, long serviceid*, long offset*, long nmax*, long sort*)
CODE

Returns:

LoginsQueryResult
CODE

This is an object with the following properties:

public string err;                    // 'OK' or 'NOK:<cause>'
CODE
public int n;                         // see below
CODE
public long[] id;                     // Unique ID of each users 
CODE
public long count;                    // see below
CODE
public string[] login;                // login name
CODE
public string[] code;                 // see below
CODE
public long[] status;                 // see below
CODE
public long[] role;                   // see below
CODE
public string[] firstname; 
CODE
public string[] name;
CODE
public string[] mail;
CODE
public string[] phone;
CODE
public string[] extrafields;          // see below
CODE
public long[] createdby;              // see below
CODE
public long[] lastauthdate;            // see below
CODE

This function returns the list of logins for the requested Service.

Input parameters :

Parameters “offset” and “nmax” are used to page requests: “offset” is the first line of the page to request (can start at 0), “nmax” is the number of lines per page (Default page size=100).

Parameter “sort” can be set to:

  • 0: no sorting

  • 1: sort by login (ascending)

  • 2: sort by login (descending)

  • 3: sort by name (ascending)

  • 4: sort by name (descending)

  • 5: sort by mail (ascending)

  • 6: sort by mail (descending)

Output values :

  • Parameter “n” returns the number of listed entries.

  • Parameter “count” returns the total number of logins, whereas parameter “n” returns the number of logins of the request.

  • Parameter “code”:

    • “ok”: The code has been used. This login should be considered as active.

    • “expired”: The code was never used and has expired. There is no more valid activation code for this login.

    • “in:<9-digit code>”: The code has not been used yet, and is inactive. Use loginActivateCode to switch the code to “active” state (see loginCreate with codetype=1)

    • “link”: The code has not been used yet, an activation link (valid for 3 weeks) was sent to the email address given at loginCreate time (see loginCreate with codetype=2)

    • “<9-digit code>”: The code is valid at present time and has not been used yet

  • Parameter “status”:

    • 0: login is active

    • 1: login is blocked (authentication requests will be rejected)

  • Parameter “role” defines the rights for this login:

    • 0: user

    • 1: manager of the service (can create, modify and delete users)

    • 2: administrator of the service (can also modify parameters of the service in the Administration Console)

  • Parameter “extrafields” is reserved for future use.

  • Parameter “createdby” is used to distinguish logins created by inWebo Aministration console from logins created by the API. Possible values:

    • 0: login created by WebConsole

    • 1: login created by API

  • Parameter “lastauthdate” gives the last authentication date for each login returned by the query as a timestamp 

loginQuery

loginQuery(long userid*, long loginid*)
CODE

Returns:

LoginQueryResult
CODE

This is an object with the following properties:

The state value “3”

For some state properties, the value may be 3. It is a mask, meaning that it is a 1 + 2 → 3 = (1) device locked + (2)pin locked)

public string err;
CODE
public string login;             // Login Name
CODE
public string code;  
CODE
public long status;  
CODE
public long role;
CODE
public string firstname;
CODE
public string name;
CODE
public string mail;
CODE
public string extrafields;
CODE
public long createdby;
CODE
public long lastauthdate;       // timestamp of the last successful authentication (0 if none)
CODE
public long iwpinblocked;       // indicates weither the user inWebo PIN is blocked (1) or not (0)
CODE
public long iwpasswordblocked;  // indicates weither the user inWebo password is blocked (1) or not (0)
CODE
public long macpasswordblocked; // indicates weither the user mAccess or dedicated PIN is blocked (1) or not (0)
CODE
public long nca;                //no. of inWebo Helium / Virtual Authenticator (browser tokens)
CODE
public long caid[];             //id of the tool
CODE
public long castate[];          //state of the tool (0:active, 1:locked; 2:pin locked; 3:(1)locked+(2)pin locked)
CODE
public string caname[];         //name of the tool
CODE
public string caalias[];        //alias of the tool (can be correlated with authenticateExtended)
CODE
public long cault[];            //type of tool (0: application (toolbar); 1: Helium)
CODE
public long cacreationdate[];   //date of tool creation / activation
CODE
public long calastauthdate[];   //tool last use date
CODE
public long nma;                //no. mobile applications (= InWebo Authenticator, can be 0 or 1)
CODE
public long maid[];             //id of the mobile application
CODE
public long mastate[];          //state of the tool (0:active, 1:locked; 2:pin locked; 3:(1)locked+(2)pin locked)
CODE
public string maname[];           //name of the mobile application
CODE
public string maalias[];          //alias of the mobile application
CODE
public long mapushenabled[];    //the mobile application has successfully registered for push notifications
CODE
public long macreationdate[];   //date of tool creation / activation
CODE
public long malastauthdate[];   //tool last use date
CODE
public long nmac;               //no. of mAccess
CODE
public long macid[];            //id of the mAccess
CODE
public long macstate[];         //state of the tool (0:active, 1:locked; 2:pin locked; 3:(1)locked+(2)pin locked)
CODE
public string macname[];        //name of the maccess
CODE
public string macalias[];       //alias of the maccess
CODE
public long macpushenabled[];   //the mobile app based on mAccess has successfully registered for push notifications
CODE
public long maccreationdate[];   //date of tool creation / activation
CODE
public long maclastauthdate[];   //tool last use date
CODE
public long nva;               //no. of Virtual Authenticator (VA)
CODE
public long vaid[];            //id of the VA
CODE
public long vastate[];         //state of the tool (0:active, 1:locked; 2:pin locked; 3:(1)locked+(2)pin locked)
CODE
public string vaname[];          //name of the tool
CODE
public string vaalias[];         //alias of the tool
CODE
public long vacreationdate[];   //date of tool creation / activation
CODE
public long valastauthdate[];   //tool last use date
CODE
public string longcode[];       //long code if loginCreate with codetype=2 used to reconstruct the activation url:
// https://www.myinwebo.com/console/activate?code=<longcode>
CODE

This function returns attributes of a particular login.

See "loginsQuery" above for parameters details. 

loginSearch

loginSearch(long userid*, long serviceid*, string loginname*, long exactmatch*, long offset*, long nmax*, long sort*)
CODE

Returns:

LoginSearchResult
CODE

This is an object with the following properties:

public string err;
CODE
public int n;
CODE
public long[] id;
CODE
public string[] login;
CODE
public string[] code;
CODE
public long[] status;
CODE
public long[] role;
CODE
public string[] firstname;
CODE
public string[] name;
CODE
public string[] mail;
CODE
public string[] phone;
CODE
public string[] extrafields;
CODE
public long[] activation_status;
CODE

This function allows looking for a user based on its login (loginname). No wildcard or regexp are permitted for the searchstring 'loginname'.

Parameter “exactmatch” can be:

  • 0: The search request will return all the logins containing the string ‘loginname’

  • 1: The search request will return the login exactly matching ‘loginname’

The return parameter “activation_status” is a mask:

  • 0: The user has not activated a device yet

  • 1: The user's mobile application (inWebo Authenticator) is active (and is not blocked)

  • 2: The user has at least one instance of inWebo Helium active (and is not blocked)

  • 3: (2+1) The user's mobile application is active and the user has at least one instance of inWebo Helium active (both not blocked)

  • 4: The user has at least one instance of inWebo Virtual Authenticator active (and is not blocked)

  • 5: (4+1) The user's mobile application is active and the user has at least one instance of inWebo Virtual Authenticator active (both not blocked)

Usage of parameters “offset”, “nmax” and “sort” are identical to loginsQuery.

loginCreate

loginCreate(long userid*, long serviceid*, string login*, string firstname, string name, string mail,
            string phone, long status*, long role*, long access*, long codetype*, string lang, string extrafields)
CODE

Returns:

LoginCreateResult
CODE

This is an object with the following properties:

public string err;
CODE
public string code;
CODE
public long id;
CODE

This function creates a login identified by the returned “id” value for the requested service. It also generates an activation code, which can be either retrieved in the “code” return parameter, or sent by Email using loginSendByMail.

This activation code should be entered by the end-user in one of the inWebo authentication tools. The tool will then become activated for this service, and available to generate OTPs for this service.

The behavior depends on the “codetype” parameter:

  • 0: An activation code is generated, valid immediately for 30 minutes

  • 1: An “inactive” activation code, valid for 3 weeks, is generated (it will become active later on, thanks to loginActivateCode)

  • 2: An activation link, valid for 3 weeks, is generated. LoginSendByMail must be used immediately after

Parameter “lang” can be “fr” or “en”.

Parameter “access” can be:

  • 0: service bookmarks are not associated to this user

  • 1: all service bookmarks are associated to this user

loginCreate will return “NOK:full” if the maximum number of users for the service has been reached, and “NOK:loginexists” if the login already exists.

Input parameters constraints and limitations

All of the input parameters must fit the following constraints and allowed characteres:

  • 'login': a-z A-Z 0-9 @ \ . _ - and space (max length allowed = 255)

  • 'firstname' and 'name': alphanumeric unicode characteres space . + - _ ' (max length allowed = 255)

  • 'extrafields': format : { "key1":"value1" [ ,"key2":"value2",...] }

    • key: alphanumeric unicode characters . _ - (max length allowed = 60)

    • value: alphanumeric unicode characters @ # { } . + - _ ' (max length allowed = 60)

    • overall max size for all extrafields = 4096

loginUpdate

loginUpdate(long userid*, long serviceid*, long loginid*, string login*, string firstname, string name, 
           string mail, string phone, long status*, long role*, string extrafields)
CODE

Returns:

loginUpdateResponse
CODE

This is an object with the following properties:

public string loginUpdateReturn
CODE

This function allows to update a service user (a login).

The string returned is a result code which can be “OK’ (success) or “NOK:<cause>” (error). The function will return “NOK:login already used” if you tried to update the login name and that login name already exists.

The input parameters constraints and limitations are the same as for loginCreate (see above)

loginSendByMail

loginSendByMail(long userid*, long serviceid*, long loginid*)
CODE

Returns:

loginSendByMailResponse
CODE

This is an object with the following properties:

public string loginSendByMailReturn
CODE

This function sends an activation link or an unlock link to the requested login per email. The login must have a valid email address previously configured with loginCreate or loginUpdate.

The string returned is a result code which can be “OK”(success) or “NOK” (error).

loginActivateCode

loginActivateCode(long userid*, long serviceid*, long loginid*)
CODE

Returns:

loginActivateCodeResponse
CODE

This is an object with the following properties:

public string loginActivateCodeReturn
CODE

The string returned can be “NOK” (error) or the inWebo activation code of the login.

To be used with logins created with codetype=1.

loginGetCodeFromLink(string code*)
CODE

Returns:

loginGetCodeFromLinkResponse
CODE

This is an object with the following properties:

public string loginGetCodeFromLinkReturn
CODE

The string returned can be “NOK” (error) or the inWebo activation code of the login.

To be used with logins created with codetype=2. In this case the loginCreate returns a 3-week long code in the “code” field to be converted into a final activation code with either loginGetCodeFromLink or loginGetInfoFromLink.

loginGetInfoFromLink(string code*)
CODE

Returns:

LoginCreateResult
CODE

With the following properties:

public string err;
CODE
public long id;
CODE
public string code;
CODE

The “id” field of the response returns the ID of the previously created login. It allows to execute further API calls to retrieve additional properties on the created login. For instance, a loginQuery would return the role or the group memberships, making it possible to trigger different activation scenarios.

To be used with logins created with codetype=2. In this case the loginCreate returns a 3-week long code in the “code” field to be converted into a final activation code with either loginGetCodeFromLink or loginGetInfoFromLink.

loginGetOTP

loginGetOTP (long userid*, long serviceid*, long loginid*)
CODE

Returns:

loginGetOTPResponse
CODE

This is an object with the following properties:

public string loginGetOTPReturn
CODE

The string returned is either the OTP (success) or “NOK:<cause>” (error).

loginDelete

loginDelete(long userid*, long serviceid*, long loginid*)
CODE

Returns:

loginDeleteResponse
CODE

This is an object with the following properties:

public string loginDeleteReturn
CODE

This function allows to delete a service user (a login).

The string returned is a result code which can be “OK” (success) or “NOK” (error).

loginResetPwd

Note : loginResetPwd is deprecated. You should use loginResetPwdExtended instead (see below)

loginResetPwd(long userid*, long serviceid*, long loginid*)
CODE

Returns:

loginResetPwdResponse
CODE

This is an object with the following properties:

public string loginResetPwdReturn
CODE

This function allows to generate a recovery code a user will be able to use to reset its password from an inWebo device that has been blocked by 3 erroneous PIN codes or passwords.

The string returned is a result code which can be “OK” (success) or “NOK:<cause>” (error).

NB: If the user has more than one service, only the current service will be unlocked. Other services, including My inWebo, will not be available.

loginResetPwdExtended

loginResetPwdExtended(long userid*, long serviceid*, long loginid*, long codetype*)
CODE

Returns:

loginResetPwdExtendedResponse
CODE

This is an object with the following properties:

public string loginResetPwdExtendedReturn
CODE

This function allows to generate a recovery code a user will be able to use to reset its password from an inWebo device that has been blocked by 3 erroneous PIN codes or passwords.

Compared to loginResetPwd, this function adds a ‘codetype’ parameter with 2 possible values:

  • 0: An unlock code is generated, valid immediately for 15 minutes

  • 2: An unlock link, valid for 2 days, is generated. LoginSendByMail must be used immediately after

The string returned is a result code which can be a numeric value (the recovery code) (success) or “NOK:<cause>” (error)..

NB: If the user has more than one service, only the current service will be unlocked. Other services, including My inWebo, will not be available.

loginResetPINErrorCounter

loginResetPINErrorCounter(long userid*, long serviceid*, long loginid*)
CODE

Returns:

loginResetPINErrorCounterResponse
CODE

This is an object with the following properties:

public string loginResetPINErrorCounterReturn
CODE

This function allows to reset the user PIN code or password error counter. It can be used only once for a given user, until he successfully authenticates again.

The string returned is a result code which can be “OK” (success) or “NOK:<cause>” (error).

If this code means an error occurs and is equal to “NOK:MULTI”, it means that this user (login) is associated to other services that do not allow to use this function.

loginRestore

loginRestore(long userid*, long serviceid*, long loginid*)
CODE

Returns:

loginRestoreResponse
CODE

This is an object with the following properties:

public string LoginRestoreReturn
CODE

This function allows to generate a restore code (ie. an activation code with codetype=0) for a user to restore its access to the service, for example if he has blocked or lost all his inWebo authentication devices. When using loginRestore all the user's properties are conserved (name, firstname, mail, ...), and also his group(s) memberships and roles.

Note that loginRestore also maintains the loginid value of the user.

When the restore code is used, all other existing inWebo devices for that user will be deleted, as if it was created for the first time with loginCreate.

Only the access to YOUR service will be restored. Accesses to other services will have to be restored one by one by contacting each service provider.

loginRestore is applicable to all possible user states (expired, activation pending and activated).

The string returned is a result code which can be either the restore code (success) or “NOK” (error).

loginAddDevice

loginAddDevice(long userid*, long serviceid*, long loginid*, long codetype*)
CODE

Returns:

loginAddDeviceResponse
CODE

This is an object with the following properties:

public string loginAddDeviceReturn
CODE

This function allows to generate a code a user will use to activate the device of its choice. 

Codetype possible values are 0 (immediate use) or 2 (long code, see above, loginCreate section).
When using a codetype=2 loginSendByMail must be used immediately after.

The string returned is a result code which can be a numeric value (the activation code) (success) or “NOK:<cause>” (error).

If an error occurs and the returned code is equal to:

  • “NOK:NoPassword”: it means the this user’s password is empty

NB: If the user has more than one service, only the current service will be activated. Other services, including My inWebo, will not be available.

loginUpdateTool

loginUpdateTool(long userid*, long serviceid*, long toolid*, string tooltype*, string name*)
CODE

Returns:

loginUpdateToolResponse
CODE

This is an object with the following properties:

public string loginUpdateToolReturn
CODE

This function allows to rename a tool for a given user. ToolID and ToolType can be obtained by using loginQuery.

  • ToolType can be ‘ma’ (for inWebo Authenticator and mAccess Web), ‘ca’ (inWebo Helium) ‘va’ (Virtual Authenticator) or ‘mac’ (mAccess).

  • ToolID can be either the corresponding ‘maid’ (inWebo Authenticator), ‘caid’ (inWebo Helium) ‘vaid’ (Virtual Authenticator) or ‘macid’ (mAccess).

The string returned is a result code which can be “OK” (success) or “NOK:<cause>” (error).

loginDeleteTool

loginDeleteTool(long userid*, long serviceid*, long toolid*, string tooltype*)
CODE

Returns:

loginDeleteToolResponse
CODE

This is an object with the following properties:

public string loginDeleteToolReturn
CODE

This function allows to delete a tool for a given user. ToolID and ToolType can be obtained by using loginQuery.

  • ToolType can be ‘ma’ (for inWebo Authenticator and mAccess Web), ‘ca’ (inWebo Helium) ‘va’ (Virtual Authenticator) or ‘mac’ (mAccess).

  • ToolID value is returned by a call to the API loginQuery, it can be either the corresponding ‘maid’ (inWebo Authenticator),
    ‘caid’ (inWebo Helium) ‘vaid’ (Virtual Authenticator) or ‘macid’ (mAccess).

The string returned is a result code which can be “OK” (success) or “NOK:<cause>” (error).

loginGetGroups

loginGetGroups (long userid*, long loginid*, long offset*, long nmax*)
CODE

Returns:

loginGetGroupsResponse
CODE

This is an object with the following properties:

public string err;
CODE
public int n;
CODE
public int count;
CODE
public long groupid;
CODE
public string name;
CODE
public long servicepolicy;
CODE
public long role;
CODE

This function returns, for a given loginid the list of groups (groupid and name) this user is member of, and their corresponding servicepolicy id.

The 'err' string returned is a result code which can be “OK” (success) or “NOK:<cause>” (error).

loginsQueryByGroup

loginsQueryByGroup (long userid*, long groupid*, long offset*, long nmax*, long sort*)
CODE

Returns:

loginsQueryByGroupResponse
CODE

This is an object with the following properties:

public string err;
CODE
public int count;
CODE
public int n;
CODE
public long id;
CODE
public string login;
CODE
public string code;
CODE
public long status;
CODE
public long role;
CODE
public string firstname;
CODE
public string name;
CODE
public string mail;
CODE
public string phone;
CODE
public string extrafields;
CODE
public long createdby;
CODE

This function returns the list of users member of this group, and their personnal informations.

The 'err' string returned is a result code which can be “OK” (success) or “NOK:<cause>” (error).

serviceGroupsQuery

serviceGroupsQuery (long userid*, long serviceid*, long offset*, long nmax*)
CODE

Returns:

serviceGroupsQueryResponse
CODE

This is an object with the following properties:

public string err;
CODE
public int n;
CODE
public int count;
CODE
public long groupid;
CODE
public string name;
CODE
public long servicepolicy;
CODE

This function returns for a given serviceid the list of known groups (groupid and name) and their corresponding servicepolicy id.

The 'err' string returned is a result code which can be “OK” (success) or “NOK:<cause>” (error).

groupAccountCreate

groupAccountCreate (long userid*, long groupid*, long loginid*, long role*)
CODE

Returns:

groupAccountCreateResponse
CODE

This function add a user identified by its 'loginid' to an existing group designed by its 'groupid'. The role of this user in the group is assigned through the integer 'role' parameter (refer to the above "loginQuery" section for possible values)

The string returned is a result code which can be “OK” (success) or “NOK” (error).

groupAccountDelete

groupAccountDelete (long userid*, long groupid*, long loginid*)
CODE

Returns:

groupAccountDeleteResponse
CODE

This function allows to remove a user identified by its 'loginid' from an existing group designed by its 'groupid'.

The string returned is a result code which can be “OK” (success) or “NOK” (error).

groupAccountQuery

groupAccountQuery (long userid*, long groupid, long *userid*)
CODE

Returns:

groupAccountQueryResponse
CODE

This is an object with the following properties:

public string err;
CODE
public long roleid;
CODE
public long loginid;
CODE
public long groupid;
CODE

This function returns for a given 'loginid' and 'groupid' the role and if this user is member of this group

The 'err' string returned is a result code which can be “OK” (success) or “NOK” (error).

groupAccountUpdate

groupAccountUpdate (long userid*, long groupid*, long loginid*, long role*)
CODE

Returns:

groupAccountUpdateResponse
CODE

This is an object with the following properties:

string
CODE

This function is used to modify the user role inside a given group identified by its groupid. The role parameter must be a valid 'roleid' corresponding to a custom role for this group.

The string returned is a result code which can be “OK” (success) or “NOK” (error).

IWDS_check

IWDS_check()
CODE

Returns:

IWDS_checkResponse
CODE

This function returns a string which can be “OK:<ServiceId>” (success) or “NOK” (error).

loginCreateBySource

loginCreateBySource (long userid*, long serviceid*, string login*, string firstname, string name, string mail,
            string phone, long status*, long role*, long access*, long codetype*, string lang, string extrafields,
            string login2, string login3, long provisioningId)
CODE

Returns:

LoginCreateResult
CODE

This function creates a login identified by the returned “id” value for the requested service.

The provisioningId parameter allows you to specify the provisioning source. Possible values:

0: created by inWebo administration console

1: created by IWDS (default value)

>1: other provisioning source

Be aware when using this setting with IWDS. When you “make a diff" during the synchronization step, the defined provisioningId will update the Created By value. You should set the provisioningId in the IWDS configuration file. See more → IWDS - Graphical Interface guide | Synchronization