# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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
# 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: createAccount, updateAccount, getAccount
# 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):
|
# 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:
|
| 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
|
| 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
|
| 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) |