Scenario: Provisioning
Support: full-sdk
The provisioningExecute command executes basic provisioning operations.
| Command | Description |
|---|---|
| PROVISIONCMD_ACTIVATE | Performs a provisioning activation operation on OneSpan Authentication Server (see PROVISIONCMD_ACTIVATE). |
| PROVISIONCMD_ASSIGN | Performs a provisioning assignment operation on OneSpan Authentication Server (see PROVISIONCMD_ASSIGN). |
| PROVISIONCMD_DSAPPACTIVATE | Performs a provisioning activation operation on OneSpan Authentication Server using DSAPP (see PROVISIONCMD_DSAPPACTIVATE). |
| PROVISIONCMD_DSAPPGENERATEACTIVATIONDATA | Generates activation data for Mobile Authenticator Studio on OneSpan Authentication Server (see PROVISIONCMD_DSAPPGENERATEACTIVATIONDATA). |
| PROVISIONCMD_DSAPPREGISTER | Performs a provisioning registration operation on OneSpan Authentication Server using DSAPP (see PROVISIONCMD_DSAPPREGISTER). |
| PROVISIONCMD_MDL_ACTIVATE | Validates the confirmation code generated by an authenticator when processing Activation Message 2 (see PROVISIONCMD_MDL_ACTIVATE). Supports Response-Only OTP validation and Secure Channel signature validation of the confirmation code. Applies to authenticators compliant with multi-device licensing (MDL). |
| PROVISIONCMD_MDL_ADD_DEVICE | Registers a new device that supports two-step activation (see PROVISIONCMD_MDL_ADD_DEVICE). Applies to authenticators compliant with multi-device licensing (MDL). |
| PROVISIONCMD_MDL_REGISTER | Generates Activation Message 1 for a specified end-user on OneSpan Authentication Server (see PROVISIONCMD_MDL_REGISTER). In a two-step activation scenario, this constitutes the first activation step. Applies to authenticators compliant with multi-device licensing (MDL). |
| PROVISIONCMD_REGISTER | Performs a provisioning registration operation on OneSpan Authentication Server (see PROVISIONCMD_REGISTER). |
| PROVISIONCMD_SERVER_TIME | Retrieves the server time to use in activation and re-activation of Mobile Authenticator Studio. The PROVISIONCMD_SERVER_TIME command supports only the PROVFLD_SERVER_TIME (output) attribute. |
Parameters
| Parameter name | Data type | Description |
|---|---|---|
| cmd | ProvisioningCmdIDEnum | Required. The operation to be executed (see Table: provisioningExecute commands). |
| attributeSet | UserAttributeSet | Required. A set containing zero or more attribute fields. |
| Parameter name | Data type | Description |
|---|---|---|
| results | ProvisioningResults | Result structure containing return and status codes and a list of zero or more result attribute fields. |
The following field attributes are available for the operations of this command:
| Attribute name | Data type | Description |
|---|---|---|
| PROVFLD_ACTIVATION_CODE | String | Activation information for the assigned authenticator. Depending on the value of PROVFLD_ACTIVATION_TYPE, the returned code is an online activation code or offline activation data. The online activation code is returned in encrypted full activation data (XFAD) format. The activation code can be encrypted, either with the user's static password (if the policy does not require local or back-end authentication) or with a custom encryption password (specified by PROVFLD_CUSTOM_ENCRYPT_PWD). If neither is specified, the activation code will not be encrypted. |
| PROVFLD_ACTIVATION_CODE_IV | String | The initial vector for PROVFLD_ACTIVATION_CODE if DSAPPv2 is used. |
| PROVFLD_ACTIVATION_MESSAGE | String | The generated activation message. Applies to authenticators compliant with multi-device licensing (MDL). |
| PROVFLD_ACTIVATION_MESSAGE_IV | String | The generated activation message in multi-device activation mode if DSAPPv2 is used. |
| PROVFLD_ACTIVATION_PASSWORD | String | Shared data for DSAPP, i.e. either activation password or authorization code. |
| PROVFLD_ACTIVATION_TYPE | Unsigned Integer | This attribute determines if the register operations (PROVISIONCMD_REGISTER, PROVISIONCMD_MDL_REGISTER) should generate online or offline activation data. Possible values:
Default value:
|
| PROVFLD_ALEA | String | A pseudo-randomly generated encryption diversifier. Up to 512 characters. Shared data plus alea must not exceed 512 characters. |
| PROVFLD_AUXILIARY_MESSAGE | String | Returned if registration is not successful. |
| PROVFLD_CESPR | String | Deprecated. The change encrypted static password request generated by the Digipass 110 applet. |
| PROVFLD_CHALLENGE | String | The challenge that was presented to the user to generate the password to verify. |
| PROVFLD_CLIENT_HASH | String | Deprecated. The PC hash generated by the DIGIPASS for Web application. |
| PROVFLD_CLIENT_IV | String | The client initial vector. |
| PROVFLD_COMPONENT_TYPE | String | The SOAP client application identifier. |
| PROVFLD_CONFIRM_NEW_STATIC_PASSWORD | String | The confirmation of the new static password to be set. |
| PROVFLD_CUSTOM_ENCRYPT_PWD | String | This is a custom encryption password that can be used to encrypt the activation code (PROVFLD_ACTIVATION_CODE). |
| PROVFLD_DELIVERY_METHOD | String | Specifies and triggers the message delivery via Message Delivery Component (MDC). If this attribute is omitted, notifications will not be sent via MDC. Possible values: |
| PROVFLD_DERIVATION_CODE | String | Contains a derivation code. Must be used when the value for the PROVFLD_REQUEST_TYPE attribute is set to 0. |
| PROVFLD_DESCRIPTION | String | A description of the authenticator instance, as added during multi-device activation. Up to 255 characters. Special characters are replaced with spaces. |
| PROVFLD_DESTINATION | String | The delivery destination, e.g. the destination email address. If this attribute is present, PROVFLD_DELIVERY_METHOD must be present as well. If the PROVFLD_DELIVERY_METHOD attribute is specified but PROVFLD_DESTINATION is omitted, the user account email address will be used. |
| PROVFLD_DEVICE_CODE | String | The code generated by an authenticator when processing the first activation message. Applies to authenticators compliant with multi-device licensing (MDL). |
| PROVFLD_DEVICE_ID | String | The identifier that refers to a specific authenticator. Applies to authenticators compliant with multi-device licensing (MDL). |
| PROVFLD_DEVICE_TYPE | String | The device type for which a new authenticator instance is created. Applies to authenticators compliant with multi-device licensing (MDL). Possible values:
|
| PROVFLD_DOMAIN | String | As output, the user's resolved domain will be specified. Up to 255 characters. |
| PROVFLD_DP_RESPONSE | String | Contains a Response-Only OTP. Must be used if the value for the PROVFLD_REQUEST_TYPE attribute is 1. |
| PROVFLD_DSAPP_VERSION | Unsigned Integer | Specifies the DSAPP protocol version number to be used. If this attribute is omitted, the default value is version 1. |
| PROVFLD_ENCRYPTED_CLIENT_PUBLIC_KEY_NONCE | String | The encrypted concatenation of the client public key and the client nonce. Exactly 136 (128+8) characters. |
| PROVFLD_ENCRYPTED_NONCES | String | The concatenation of the server and client nonces encrypted with the chsKey. |
| PROVFLD_ENCRYPTED_SERVER_NONCE | String | The encrypted server nonce received from the client. |
| PROVFLD_ENCRYPTED_SERVER_PUBLIC_KEY | String | The server public key encrypted with chsKey. |
| PROVFLD_EVENT_REACTIVATION_COUNTER | String | Output for the provisioningRegister command. |
| PROVFLD_EVENT_REACTIVATION_COUNTER_IV | String | Output for the provisioningRegister command in standard activation mode if DSAPPv2 is used. |
| PROVFLD_FIDO2_PUBLIC_KEY | String | The public key generated by an authenticator during a FIDO2 registration ceremony (Base64 encoded). It is used to bind authenticator instances with FIDO2 instances (see Multi-device activation with FIDO2 device binding). For more information about retrieving that key, refer to the Web Authentication specification, available at: https://w3c.github.io/webauthn/ (last accessed on September 2, 2026). |
| PROVFLD_NEW_STATIC_PASSWORD | String | The new static password to be set. |
| PROVFLD_ORGANIZATIONAL_UNIT | String | Indicates the user's resolved organizational unit. Up to 255 characters. |
| PROVFLD_REGISTRATIONID | String | |
| PROVFLD_REQUEST_TYPE | Unsigned Integer | Defines if the authenticator is activated with an OTP (PROVFLD_DP_RESPONSE) or a derivation code with device-binding (PROVFLD_DERIVATION_CODE). If this attribute is omitted, the authenticator is activated with an OTP. |
| PROVFLD_SERVER_IV | String | The server initial vector. |
| PROVFLD_SERIAL_NO | String | The serial number of the authenticator for which the activation code has been generated. When used as an input parameter for PROVISIONCMD_MDL_REGISTER, the serial number needs to be already assigned to the user. Otherwise, activation message generation will fail. Exactly 10 characters. |
| PROVFLD_SERVER_NONCE | String | |
| PROVFLD_SERVER_TIME | Integer | The current system Unix time (POSIX time or UNIX Epoch time), i.e. the number of seconds that have elapsed since 00:00:00 Thursday, 1 January 1970, Coordinated Universal Time (UTC), not counting leap seconds. Output attribute of the PROVISIONCMD_SERVER_TIME command. |
| PROVFLD_SIGNATURE | String | The signature generated by the authenticator when processing Activation Message 2. |
| PROVFLD_STATIC_PASSWORD | String | The current static password of the user. |
| PROVFLD_STATUS_MESSAGE | String | Returned if registration is not successful. |
| PROVFLD_USERID | String | The user ID as provided by the calling application (no specific format is required). As output, the resolved user ID will be specified. Up to 255 characters. |
| PROVFLD_WEB_PUBLIC_KEY | String | A diversifier value to prevent man-in-the-middle (MITM) attacks. If this parameter is NULL, diversification will not be applied. |
PROVISIONCMD_REGISTER
The following attributes can be specified in the attributeSet input parameter of this command:
The following attributes will be specified in the results output parameter of this command:
PROVISIONCMD_ACTIVATE
Once the one-time password (OTP) has been successfully validated, this command ends the authenticator grace period.
The following attributes can be specified in the attributeSet input parameter of this command:
The following attributes will be specified in the results output parameter of this command:
PROVISIONCMD_ASSIGN
The following attributes can be specified in the attributeSet input parameter of this command:
The following attributes will be specified in the results output parameter of this command:
| Attribute name | Returned? |
|---|---|
| PROVFLD_AUXILIARY_MESSAGE | Always (in error case) |
| PROVFLD_STATUS_MESSAGE | Always (in error case) |
PROVISIONCMD_DSAPPREGISTER
The following attributes can be specified in the attributeSet input parameter of this command:
The following attributes will be specified in the results output parameter of this command:
PROVISIONCMD_DSAPPACTIVATE
Once the one-time password (OTP) has been successfully validated, this command ends the authenticator grace period.
The following attributes can be specified in the attributeSet input parameter of this command:
The following attributes will be specified in the results output parameter of this command:
PROVISIONCMD_DSAPPGENERATEACTIVATIONDATA
The following attributes can be specified in the attributeSet input parameter of this command:
The following attributes will be specified in the results output parameter of this command:
PROVISIONCMD_MDL_REGISTER
Generates Activation Message 1 for a specified end-user on OneSpan Authentication Server. In a two-step activation scenario, this constitutes the first activation step.
Applies to authenticators compliant with multi-device licensing (MDL).
Parameters
The following attributes can be specified in the attributeSet input parameter of this command:
| Attribute name | Input |
|---|---|
| PROVFLD_ACTIVATION_TYPE | Optional |
| PROVFLD_COMPONENT_TYPE | Mandatory |
| PROVFLD_DOMAIN | Optional |
| PROVFLD_FIDO2_PUBLIC_KEY | Optional |
| PROVFLD_SERIAL_NO | Optional |
| PROVFLD_STATIC_PASSWORD | Mandatory |
| PROVFLD_USERID | Mandatory |
The PROVFLD_FIDO2_PUBLIC_KEY attribute is used for device binding of FIDO2–capable authenticators, such as DIGIPASS FX2 (see Multi-device activation with FIDO2 device binding).
The following attributes will be specified in the results output parameter of this command:
| Attribute name | Returned? |
|---|---|
| PROVFLD_ACTIVATION_MESSAGE | Always |
| PROVFLD_AUXILIARY_MESSAGE | Always (in error case) |
| PROVFLD_DOMAIN | Always |
| PROVFLD_ORGANIZATIONAL_UNIT | Optional |
| PROVFLD_REGISTRATIONID | Always |
| PROVFLD_SERIAL_NO | Always |
| PROVFLD_STATUS_MESSAGE | Always (in error case) |
| PROVFLD_USERID | Always |
PROVISIONCMD_MDL_ADD_DEVICE
Verifies the device code generated by the authenticator based on Activation Message 1. It creates a new authenticator instance for the authenticator license and returns Activation Message 2. This constitutes the second activation step.
Applies to authenticators compliant with multi-device licensing (MDL).
Parameters
The following attributes can be specified in the attributeSet input parameter of this command:
| Attribute name | Optionality | Remarks |
|---|---|---|
| PROVFLD_CLIENT_IV | Optional | Mandatory if PROVISIONCMD_DSAPPGENERATEACTIVATIONDATA was used to generate Activation Message 1. |
| PROVFLD_COMPONENT_TYPE | Mandatory | |
| PROVFLD_DESCRIPTION | Optional | |
| PROVFLD_DEVICE_CODE | Mandatory | |
| PROVFLD_ENCRYPTED_SERVER_NONCE | Optional | Mandatory if PROVISIONCMD_DSAPPGENERATEACTIVATIONDATA was used to generate Activation Message 1. |
| PROVFLD_REGISTRATIONID | Mandatory |
The following attributes will be specified in the results output parameter of this command:
| Attribute name | Returned? |
|---|---|
| PROVFLD_ACTIVATION_MESSAGE | Always |
| PROVFLD_AUXILIARY_MESSAGE | Always (in error case) |
| PROVFLD_DEVICE_ID | Always |
| PROVFLD_DEVICE_TYPE | Always |
| PROVFLD_REGISTRATIONID | Always |
| PROVFLD_SERIAL_NO | Always |
| PROVFLD_STATUS_MESSAGE | Always (in error case) |
PROVISIONCMD_MDL_ACTIVATE
Once the one-time password (OTP) has been successfully validated, this command ends the authenticator grace period.
The following attributes can be specified in the attributeSet input parameter of this command:
| Attribute name | Optionality |
|---|---|
| PROVFLD_COMPONENT_TYPE | Mandatory |
| PROVFLD_REGISTRATIONID | Mandatory |
| PROVFLD_SIGNATURE | Mandatory |
The following attributes will be specified in the results output parameter of this command: