Introduction

SignicatID (SCID) is a service with a SOAP web service interface. It is used for creating and manipulating accounts and other objects relevant for Signicat Connect and Assure.

The service may be used from any platform capable of making a SOAP web service call.

Signicat provides several connector kits with wrapper classes for accessing the web service. A connector kit may or may not be used when calling the service.

Location

The WSDL for the service is available at:

Infrastructure
Location
Pre-production https://preprod.signicat.com/ws/scid-v2?wsdl
Production https://id.signicat.com/ws/scid-v2?wsdl

Note!The only difference between the wsdl in preprod and production is the soap address location attribute.

List of methods

Method
Description
createAccount Used for creation of end-user accounts
deleteAccount Used for deletion of end-user accounts
updateAccount Used for updating existing accounts (adding and removal of account properties)
createArtifact Used for creating of artifacts for an existing account
addDevice Used to add a new authentication device to an existing account
deleteDevice Used to remove an existing authentication device from an existing account
getDevices Used for listing of devices of an existing account
getAccount Used to obtain information about an existing account
getAccountActivity Used to obtain activity information for an existing account
getAccountHistory Used to obtain historic information about an existing account. The historic information
means: the operations executed on the account using Web Service API
lockAccount Used to lock an account and invalidate any attempt to use it
unlockAccount Used to unlock account.
unlockAccountPassword Used to unlock account password (after too many invalid attempts)
approveAccount Used to change the state of the account (after manual approval)
listPendingAccounts Used to obtain a list of the accounts in PENDING state
getMultipleAccounts Used to obtain basic info about multiple accounts

Common request parameters

The majority of requests needs following parameters.

Name Data type Mandatory
Description
service String yes The name of the customer service (the customer account).
password String yes The password for this service. This is different in preprod and production.
domain String no The customer’s sub-domain.
Together with service and domain creates a unique identifier of the account in SignicatID space.
If not given, the value ‘default’ is used
external_reference String yes,
all but 2 requests
The customer’s reference to the end-user, account name.
Must be unique in the scope of service/domain
The only two requests that do not use this parameter are: listPendingAccounts and getMultipleAccounts

Note! These parameters will NOT be listed in the parameter list for each of the requests.

Common error responses

The majority of errors deals with missing or incorrect method’s mandatory parameters. In that case, returned fault strings follow simple pattern:

Failed to <description of the operation that was executed>: <String that informs about missing parameter>

Missing or incorrect parameter
soap:Fault/faultstring
service or password Failed to <operation>: Service is invalid or password is incorrect
external_reference Failed to <operation>: Account not found
or
Failed to <operation>: Account or device not found
in device related request
device name in device related requests Failed to <operation>: Account or device not found

createAccount

Purpose

This method is used for creation of the account.

Parameters

In addition to Common request parameters, this request requires has following parameters

Name Data type Mandatory Description
properties List of AccountProperty No The properties of the account. See the data type specification for AccountProperty
activated Boolean No The state of the created account depends of this parameter:
If false or not given, account is set in NOT_ACTIVATED state and can not be used before it is activated
If true, account is set in ACTIVATED state

Return value

Name Data type Description
result String Value: ‘created’
external_reference String
The value that was sent in request

Error response

In addition to responses listed in Common error responses, this method may return following:

deleteAccount

Purpose

This method is used for deletion of the account.

Parameters

This method has only parameters shown in Common request parameters.

Return value

Name Data type Description
result String Value: ‘deleted’
external_reference String
The value that was sent in request

Error response

See Common error responses

updateAccount

Purpose

This method is used for update of an existing accounts (adding and removal of account properties)

Parameters

In addition to Common request parameters, this request requires has following parameters

Name Data type Mandatory Description
properties List of AccountProperty No The new set of the properties for the account.
See the data type specification for AccountProperty

Operation properties

Neither property names nor values are case-sensitive

Return value

Name Data type Description
result String Value: ‘updated’
external_reference String
The value that was sent in request

Error response

In addition to responses listed in Common error responses, this method may return following:

createArtifact

Purpose

This method is used for creating artifact. It is a token that is written onto the account in question. The subsequent operation on the account may verify the existence and validity of the artifact (increasing the security)

The artifact will have a configurable lifetime (default is 30 seconds) from the moment is it created. You should create the artifact just in time before you redirect the end user to Signicat.

Parameters

This method has only parameters shown in Common request parameters.

Return value

Name Data type Description
artifact String A token with a configurable lifetime (default 30 seconds)

Error response

See Common error responses

addDevice

Purpose

This method is used for adding a authentication device to an existing account.

Parameters

In addition to Common request parameters, this request requires has following parameters

Name Data type Description
device DeviceForAdd See the data type specification for DeviceForAdd
activated Boolean The state of the created device depends of this parameter:
If false or not given, device is created in NOT_ACTIVATED state and can not be used for authentication before it is activated.
If true, device is created in ACTIVATED state

Return value

Name Data type Description
result String Value: ‘created’
external_reference String
The value that was sent in request

Error response

In addition to responses listed in Common error responses, this method may return following:

deleteDevice

Purpose

This method is used for removal of an authentication device from an existing account.

Parameters

In addition to Common request parameters, this request requires has following parameters

Name Data type Description
device_name String The name of the device to delete

Return value

Name Data type Description
result String Value: ‘deleted’
external_reference String
The value that was sent in request

Error response

See Common error responses

getDevices

Purpose

This method is used for listing of all devices registered for an existing account.

Parameters

This method has only parameters shown in Common request parameters.

Return value

Name Data type Description
devices List of Device See the data type specification for Device

Error response

See Common error responses

getAccount

Purpose

This method is used for obtaining information about an existing account.

Parameters

This method has only parameters shown in Common request parameters.

Return value

Name Data type Description
account AccountInfo See the data type specification for AccountInfo

Error response

See Common error responses

getAccountActivity

Purpose

This method is used for obtaining information about activity for an existing account.

Parameters

This method has only parameters shown in Common request parameters.

Return value

Name Data type Description
external_reference String The value that was sent in request
activity-list List of AccountActivity See the data type specification for AccountActivity

Error response

If activity for non-existing account or account that is not yet used (no activity at all), following faultstring is returned: Failed to get account activity: No account activity found

getAccountHistory

Purpose

This method is used for obtaining information about historic events in the lifetime of an existing account.

Parameters

This method has only parameters shown in Common request parameters.

Return value

Name Data type Description
external_reference String Reflects the value that was sent in request
events List of AccountEvent See the data type specification for AccountEvent

Error response

See Common error responses

lockAccount

Purpose

This method is used for locking of the account. It will effectively invalidate every attempt to use the account.

Upon successful execution, the state of the account will be changed. Information about the previous state will be preserved, so when (and if) the account is unlocked (see unlockAccount), the state of the account will be restored

Parameters

This method has only parameters shown in Common request parameters.

Return value

Name Data type Description
result String Value: ‘account locked’
external_reference String
The value that was sent in request

Error response

See Common error responses

unlockAccount

Purpose

This method is used for unlocking of the already locked account. The state of the account prior to lock (see lockAccount) is restored.

Executing this method on account that is not locked, does not have any effect

Parameters

This method has only parameters shown in Common request parameters.

Return value

Name Data type
Description
result String Value: ‘account unlocked’
external_reference String
The value that was sent in request

Error response

See Common error responses

approveAccount

Purpose

This method is used when customer wants to approve user, after manual approval (based on information collected during assure process)

The method changes the state of the account to ACTIVATED. Executing this method on account that is not in state PENDING, does not have any effect

Parameters

This method has only parameters shown in Common request parameters.

Return value

Name Data type Description
result String Value: ‘account approved’
external_reference String
The value that was sent in request

Error response

In addition to responses listed in Common error responses, this method may return following:

unlockAccountPassword

Purpose

This method is used for unlocking of the account’s password. The password is locked if user, during authentication, supplies wrong password too many times..

Parameters

This method has only parameters shown in Common request parameters.

Return value

Name Data type Description
result String Value: ‘password unlocked’
external_reference String
The value that was sent in request

Error response

See Common error responses

listPendingAccounts

Purpose

This method is used to obtain a list of the accounts in PENDING state.

Parameters

This method has only parameters shown in Common request parameters. Note! The external_reference parameter is not used

Return value

Name Data type Description
accountnames List of AccountNameState See the data type specification for AccountNameState

Error response

See Common error responses

getMultipleAccounts

Purpose

This method is used to obtain a list of the multiple accounts. It is quite similar to getAccount method, except that properties of the account are not returned.

Parameters

This method has only parameters shown in Common request parameters. Note! Instead of external_reference parameter, the following parameter is used:

Name Data type Description
external_references List of ExternalReference See the data type specification for ExternalReference

Return value

Name Data type Description
accounts List of BasicAccountInfo See the data type specification for BasicAccountInfo

Error response

In addition to responses listed in Common error responses, this method may return following:

Data type: AccountProperty

Description

This data type contains attributes that describes a property of an account. It is used in following requests: createAccountupdateAccountgetAccount

Fields

Name
Data type
Description
name String The attribute name
value String
The attribute value

Data type: DeviceForAdd

Description

This data type describes an authentication device that will be added to an account. It is used in following request(s): addDevice

Fields

Name Data type Description
id String The identifier of the device, varies with device type.
E.g.: For email device: email address, for sms device: mobile telephone number
name String
The name of the device
type String One of the following type (lowercase):

  • email
  • sms
  • totp

Note! For ‘sms’: It is recommended to enter country code with mobile telephone number
(Otherwise, the unexpected results may occur – the processing will be dependent on the setting in SignicatID)

Data type: Device

Description

This data type describes an authentication device that exists on an account.  It is used in following request(s): getDevices

Fields

Name Data type Description
id String The identifier of the device, varies with device type.
name String
The name of the device
type String One of the following:

  • email
  • sms
  • totp
  • yubi
  • mobileid
state String The state of the device: NOT_ACTIVATED or ACTIVATED
is_preregistered String true or false
Indicates if the device is added using addDevice or it was added by other means (e.g. SignicatID’s device registration method)

Data type: AccountInfo

Description

This data type contains relevant information about an existing account. Only list of the devices is not returned, see getDevices.  It is used in following request(s): getAccount

Fields

Name Data type
Description
domain String The domain of the account. The same one as supplied in the request
external_reference String
The name of the account. The same one as supplied in the request
created Date Creation date and time (e.g. 2016-10-31T09:59:11.000+01:00)
state String The state of the account. One of

  • NOT_ACTIVATED
  • ACTIVATED
  • PENDING

In addition, in case that account is locked, prefix LOCKED_ appears in front of the state string

properties List of AccountProperty List of the account properties. See the data type specification for AccountProperty
locked String true – Only if password is locked, otherwise, the field is not returned

Data type: AccountActivity

Description

This data type contains relevant information about operations executed on account. It is used in following request(s): getAccountActivity

Fields

Name
Data type
Description
created String The date the activity took place
operation String
Operation type. Depends on the functionality and version of SignicatID.

Some values: ACCOUNT_ACTIVATION, DEVICE_ACTIVATION,
DEVICE_REGISTRATION, AUTHENTICATION, PASSWORD_RESET,
PASSWORD_CHANGE, EXTENDID, ESTABLISHID, PROOFID.

authentication List of AuthenticationMethod See the data type specification for AuthenticationMethod

Data type: AuthenticationMethod

Description

This data type describes an element of the (potentially) multiple authentications steps carried out during one AccountActivity. It is used in following request(s): getAccountActivity

Fields & attributes

Name
Data type
Description
type String The type of the authentication method. Depends on the functionality and version of SignicatID.

Some possible values: SMS_OTP, EMAIL_OTP, MOBILEID, TOTP,
SIGNICATDATA, NBID, NBID_MOBILE, IDIN, NEMID, TUPAS, SBID,
SIGNICATPAPER, FACEBOOK, GOOGLE, AMAZON, PAYPAL etc ..

attribute AuthenticationAttribute
Additional Info

Data type: AuthenticationAttribute

Description

This data type adds additional info to AuthenticationMethod. The content of the field (and attribute) is strongly dependent on the type of the AuthenticationMethod. It is used in following request(s): getAccountActivity

Fields & Attributes

Name Data type Description
name String The description of the proofing method or authentication device used.
For SMS_OTP, EMAIL_OTP it will be the name of the device
For other proofing method it will be the name of the proofing method
attribute String
Varies with the context (proofing method or authentication device used)
For SMS_OTP, EMAIL_OTP it will be device id of the device
For other proofing methods it will be the key method information
(e.g.: NBID -> personal number, FACEBOOK -> id)

Data type: AccountEvent

Description

This data type contains relevant information about following events in the account lifetime:

It is used in following request(s): getAccountHistory

Fields

Name Data type Description
event_source String Always WS
event_type String
Either ILLEGAL_ACCOUNT_OPERATION, or string that indicates the web-service operation executed on the account:
One of ACCOUNT_CREATED, ACCOUNT_UPDATED, ACCOUNT_DELETED, DEVICE_ADDED, DEVICE_DELETED etc …
event_message String Only if type is ILLEGAL_ACCOUNT_OPERATION. Message is always ‘Attempt to access account with wrong state’
Otherwise not returned.
created String The date and time when the event took place

Data type: AccountNameState

Description

This data type contains the name of the account in pending state. (Note! The state is also returned/confirmed). The data type is used in following request(s): listPendingAccounts

Size limit is 30 (the method returns at most 30 accounts)

Fields

Name Data type Description
external_reference String The name of the account
state String ‘PENDING’

Data type: ExternalReference

Description

This data type contains the name of the account. The data type is used in following request(s): getMultipleAccounts

Fields

Name Data type Description
external_reference String The name of the account

Data type: BasicAccountInfo

Description

This data type contains the basic information about account. It is quite similar to AccountInfo, but creation time and properties of the account are not returned. The data type is returned from following request(s): getMultipleAccounts

Fields

Name Data type Description
domain String The domain of the account. The same one as supplied in the request
external_reference String
The name of the account. The same one as supplied in the request
state String The state of the account. One of

  • NOT_ACTIVATED
  • ACTIVATED
  • PENDING

In addition, in case that account is locked, prefix LOCKED_ appears in front of the state string

locked String This field is shown ONLY if account is in the state ACTIVATED. (it is the only state that may have the password locked)