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