link

# SignicatID (SCID) API v2

# 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 authentication and onboarding. 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 pre-production 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 information about multiple accounts

# Common request parameters

The majority of requests need the 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 pre-production and production.
domain String no The customer's sub-domain. Together with service and domain creates a unique identifier of the account in the 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

Important

These parameters will not be listed in the parameter list for each of the requests.

# Common error responses

The majority of errors deal with missing or incorrect methods' 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 the 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:

  • Attempt to create account that already exists: Failed to create account: Account already exists
  • Attempt to create account and add key attribute with value that already exists: Failed to create account: The value of the key attribute: <attr name> is not unique

# 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 the 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

  • If property with name already exists, the value will be overwritten with the new one
  • If new value is empty (''), the whole property will be removed from the account.
    • If the property didn't exist in the first place, nothing will happen (but 'updated' status will be returned)

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:

  • Attempt to update account and add key attribute with value that already exists: Failed to update account: The value of the key attribute: <attr name> is not unique

# 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 the 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:

  • Attempt to add device that already exists: Failed to add device (Device already exists?): System error in server

# 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 the 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 the customer wants to approve the end-user, after manual approval (based on information collected during the onboarding 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:

  • If account is not in PENDING state: Failed to approve account: Invalid account state: <state>

# unlockAccountPassword

# Purpose

This method is used for unlocking of the account's password. The password is locked if the end-user, during authentication, supplies the 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 in use.

# 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.

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:

  • If too many references supplied: Failed to get accounts:  Invalid request. The number of accounts is limited to 50

# 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
For 'sms', it is recommended to enter the country code with the 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 information 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:

  • Any Web Service operation executed on account.
  • Attempt to use account when it is not in valid state (e.g, trying to log in, even when account is NOT_ACTIVATED or LOCKED)

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. 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)
Last updated: 7/21/2021, 1:18:18 PM