SOAP Service Methods

This is a reference documentation of the methods published by the PowerAuth Server SOAP service. It reflects the SOAP service methods as they are defined in the WSDL files:

• serviceV3.wsdl
• serviceV2.wsdl

The versioning of SOAP methods is described in chapter SOAP Method Compatibility.

The following v3 methods are published using the service:

• System Status
  • getSystemStatus
  • getErrorCodeList
• Application Management
  • getApplicationList
  • getApplicationDetail
  • lookupApplicationByAppKey
  • createApplication
  • createApplicationVersion
  • unsupportApplicationVersion
  • supportApplicationVersion
• Activation Management
  • getActivationListForUser
  • initActivation
  • prepareActivation
  • createActivation
  • updateActivationOtp
  • commitActivation
  • getActivationStatus
  • removeActivation
  • blockActivation
  • unblockActivation
  • lookupActivations
  • updateStatusForActivations
• Signature Verification
  • verifySignature
  • verifyECDSASignature
• Offline Signatures
  • createPersonalizedOfflineSignaturePayload
  • createNonPersonalizedOfflineSignaturePayload
  • verifyOfflineSignature
• Token Based Authentication
  • createToken
  • validateToken
  • removeToken
• Vault Unlocking
  • vaultUnlock
• Signature Audit Log
  • getSignatureAuditLog
• Activation History
  • getActivationHistory
• Integration Management
  • createIntegration
  • getIntegrationList
  • removeIntegration
• Callback URL Management
  • createCallbackUrl
  • getCallbackUrlList
  • removeCallbackUrl
• End-To-End Encryption
  • getEciesDecryptor
• Activation Versioning
  • startUpgrade
  • commitUpgrade
• Activation Recovery
  • createRecoveryCode
  • confirmRecoveryCode
  • lookupRecoveryCodes
  • revokeRecoveryCodes
  • recoveryCodeActivation
  • getRecoveryConfig
  • updateRecoveryConfig The following v2 methods are published using the service:
• Activation Management
  • prepareActivation (v2)
  • createActivation (v2)
• Token Based Authentication
  • createToken (v2)
• Vault Unlocking
  • vaultUnlock (v2)
• End-To-End Encryption
  • getNonPersonalizedEncryptionKey (v2)
  • getPersonalizedEncryptionKey (v2)

System status

Methods used for getting the PowerAuth Server system status.

Method ‘getSystemStatus’

Get the server status information.

Request

GetSystemStatusRequest

• no attributes

Response

GetSystemStatusResponse

Method ‘getErrorCodeList’

Get the list of all error codes that PowerAuth Server can return.

Request

GetErrorCodeListRequest

Response

GetErrorCodeListResponse

GetErrorCodeListResponse.Error

Application management

Methods related to the management of applications and application versions.

Method ‘getApplicationList’

Get list of all applications that are present in this PowerAuth Server instance.

Request

GetApplicationListRequest

• no attributes

Response

GetApplicationListResponse

GetApplicationListRequest.Application

Method ‘getApplicationDetail’

Get detail of application with given ID or name, including the list of versions.

Request

GetApplicationDetailRequest

Response

GetApplicationDetailResponse

GetApplicationDetailResponse.Version

Method ‘lookupApplicationByAppKey’

Find application using application key.

Request

LookupApplicationByAppKeyRequest

Response

LookupApplicationByAppKeyResponse

Method ‘createApplication’

Create a new application with given name.

Request

CreateApplicationRequest

Response

CreateApplicationResponse

Method ‘createApplicationVersion’

Create a new application version with given name for a specified application.

Request

CreateApplicationVersionRequest

Response

CreateApplicationVersionResponse

Method ‘unsupportApplicationVersion’

Mark application version with given ID as “unsupported”. Signatures constructed using application key and application secret associated with this versions will be rejected as invalid.

Request

UnsupportApplicationVersionRequest

Response

UnsupportApplicationVersionResponse

Method ‘supportApplicationVersion’

Mark application version with given ID as “supported”. Signatures constructed using application key and application secret associated with this versions will be evaluated the standard way.

Request

SupportApplicationVersionRequest

Response

SupportApplicationVersionResponse

Activation management

Methods related to activation management.

Method ‘initActivation’

Create (initialize) a new activation for given user and application. If both activationOtpValidation and activationOtp optional parameters are set, then the same value of activation OTP must be later provided for the confirmation.

After calling this method, a new activation record is created in CREATED state.

Request

InitActivationRequest

Response

InitActivationResponse

Method ‘prepareActivation’

Assure a key exchange between PowerAuth Client and PowerAuth Server and prepare the activation with given ID to be committed. Only activations in CREATED state can be prepared.

If optional activationOtp value is present in ECIES payload, then the value must match the OTP stored in activation’s record and OTP validation mode must be ON_KEY_EXCHANGE.

After successfully calling this method, activation is in PENDING_COMMIT or ACTIVE state, depending on the presence of an activation OTP in ECIES payload:

Request

PrepareActivationRequest

ECIES request should contain following data (as JSON):

• activationName - Visual representation of the device, for example “Johnny’s iPhone” or “Samsung Galaxy S”.
• devicePublicKey - Represents a public key KEY_DEVICE_PUBLIC (base64-encoded).
• extras - Any client side attributes associated with this activation, like a more detailed information about the client, etc.
• platform - User device platform, e.g. ios, android, hw and unknown.
• deviceInfo - Information about user device, e.g. iPhone12,3.
• activationOtp - Optional activation OTP for confirmation. The value must be provided in case that activation was initialized with ActivationOtpValidation set to ON_KEY_EXCHANGE.

Response

PrepareActivationResponse

ECIES response contains following data (as JSON):

• activationId - Represents a long ACTIVATION_ID that uniquely identifies given activation records.
• serverPublicKey - Public key KEY_SERVER_PUBLIC of the server (base64-encoded).
• ctrData - Initial value for hash-based counter (base64-encoded).
• activationRecovery - Information about activation recovery which is sent only in case activation recovery is enabled.
  • recoveryCode - Recovery code which uses 4x5 characters in Base32 encoding separated by a “-“ character.
  • puk - Recovery PUK with unique PUK used as secret for the recovery code.

Method ‘createActivation’

Create an activation for given user and application, with provided maximum number of failed attempts and expiration timestamp, including a key exchange between PowerAuth Client and PowerAuth Server. Prepare the activation to be committed later.

If optional activationOtp value is set, then the activation’s OTP validation mode is set to ON_COMMIT. The same OTP value must be later provided in CommitActivation method, to complete the activation.

After successfully calling this method, activation is in PENDING_COMMIT state.

Request

CreateActivationRequest

ECIES request should contain following data (as JSON):

• activationName - Visual representation of the device, for example “Johnny’s iPhone” or “Samsung Galaxy S”.
• devicePublicKey - Represents a public key KEY_DEVICE_PUBLIC (base64-encoded).
• extras - Any client side attributes associated with this activation, like a more detailed information about the client, etc.
• platform - User device platform, e.g. ios, android, hw and unknown.
• deviceInfo - Information about user device, e.g. iPhone12,3.

Response

CreateActivationResponse

ECIES response contains following data (as JSON):

• activationId - Represents a long ACTIVATION_ID that uniquely identifies given activation records.
• serverPublicKey - Public key KEY_SERVER_PUBLIC of the server (base64-encoded).
• ctrData - Initial value for hash-based counter (base64-encoded).
• activationRecovery - - activationRecovery - Information about activation recovery which is sent only in case activation recovery is enabled.
  • recoveryCode - Recovery code which uses 4x5 characters in Base32 encoding separated by a “-“ character.
  • puk - Recovery PUK with unique PUK used as secret for the recovery code.

Method ‘updateActivationOtp’

Update activation OTP for activation with given ID. Only non-expired activations in PENDING_COMMIT state, with OTP validation set to NONE or ON_COMMIT, can be altered.

After successful, activation OTP is updated and the OTP validation is set to ON_COMMIT.

Request

UpdateActivationOtpRequest

Response

UpdateActivationOtpResponse

Method ‘commitActivation’

Commit activation with given ID. Only non-expired activations in PENDING_COMMIT state can be committed.

If optional activationOtp value is set, then the value must match the OTP stored in activation’s record and OTP validation mode must be ON_COMMIT.

After successful commit, activation is in ACTIVE state.

Request

CommitActivationRequest

Response

CommitActivationResponse

Method ‘getActivationStatus’

Get status information and all important details for activation with given ID.

Request

GetActivationStatusRequest

Response

GetActivationStatusResponse

Method ‘removeActivation’

Remove activation with given ID. This operation is irreversible. Activations can be removed in any state. After successfully calling this method, activation is in REMOVED state.

Request

RemoveActivationRequest

Response

RemoveActivationResponse

Method ‘getActivationListForUser’

Get the list of all activations for given user and application ID. If no application ID is provided, return list of all activations for given user.

Request

GetActivationListForUserRequest

Response

GetActivationListForUserResponse

GetActivationListForUserResponse.Activation

Method ‘blockActivation’

Block activation with given ID. Activations can be blocked in ACTIVE state only. After successfully calling this method, activation is in BLOCKED state.

Request

BlockActivationRequest

Response

BlockActivationResponse

Method ‘unblockActivation’

Unblock activation with given ID. Activations can be unblocked in BLOCKED state only. After successfully calling this method, activation is in ACTIVE state and failed attempt counter is set to 0.

Request

UnblockActivationRequest

Response

UnblockActivationResponse

Method ‘lookupActivations’

Lookup activations using query parameters.

Request

LookupActivationsRequest

Response

LookupActivationsResponse

LookupActivationsResponse.Activation

Method ‘updateStatusForActivations’

Update status for activations identified using their identifiers.

Request

UpdateStatusForActivationsRequest

Response

UpdateStatusForActivationsResponse

Signature verification

Methods related to signature verification.

Method ‘verifySignature’

Verify signature correctness for given activation, application key, data and signature type.

Request

VerifySignatureRequest

Response

VerifySignatureResponse

Method ‘verifyECDSASignature’

Verify asymmetric ECDSA signature correctness for given activation and data.

Request

VerifyECDSASignatureRequest

Response

VerifyECDSASignatureResponse

Method ‘createPersonalizedOfflineSignaturePayload’

Create a data payload used as a challenge for personalized off-line signatures.

Request

CreatePersonalizedOfflineSignaturePayloadRequest

Response

CreatePersonalizedOfflineSignaturePayloadResponse

Method ‘createNonPersonalizedOfflineSignaturePayload’

Create a data payload used as a challenge for non-personalized off-line signatures.

Request

CreateNonPersonalizedOfflineSignaturePayloadRequest

Response

CreateNonPersonalizedOfflineSignaturePayloadResponse

Method ‘verifyOfflineSignature’

Verify off-line signature of provided data.

Request

VerifyOfflineSignatureRequest

Response

VerifyOfflineSignatureResponse

Token Based Authentication

Method ‘createToken’

Create a new token for the simple token-based authentication.

Request

CreateTokenRequest

ECIES request should contain following data (an empty JSON object):

{}

Response

CreateTokenResponse

ECIES response contains following data (example):

{
   "tokenId": "d6561669-34d6-4fee-8913-89477687a5cb",  
   "tokenSecret": "VqAXEhziiT27lxoqREjtcQ=="
}

Method ‘validateToken’

Validate token digest used for the simple token-based authentication.

Request

ValidateTokenRequest

Response

ValidateTokenResponse

Method ‘removeToken’

Remove token with given ID.

Request

RemoveTokenRequest

Response

RemoveTokenResponse

Vault unlocking

Methods related to secure vault.

Method ‘vaultUnlock’

Get the encrypted vault unlock key upon successful authentication using PowerAuth Signature.

Request

VaultUnlockRequest

ECIES request should contain following data:

{
    "reason": "..."
}

You can provide following reasons for a vault unlocking:

• ADD_BIOMETRY - call was used to enable biometric authentication.
• FETCH_ENCRYPTION_KEY - call was used to fetch a generic data encryption key.
• SIGN_WITH_DEVICE_PRIVATE_KEY - call was used to unlock device private key used for ECDSA signatures.
• NOT_SPECIFIED - no reason was specified.

Response

VaultUnlockResponse

ECIES response contains following data (example):

{
    "activationId": "c564e700-7e86-4a87-b6c8-a5a0cc89683f",
    "encryptedVaultEncryptionKey": "QNESF9QVUJMSUNfS0VZX3JhbmRvbQ=="
}

Signature audit

Methods related to signature auditing.

Method ‘getSignatureAuditLog’

Get the signature audit log for given user, application and date range. In case no application ID is provided, event log for all applications is returned.

Request

SignatureAuditRequest

Response

SignatureAuditResponse

SignatureAuditResponse.Item

Activation history

Get activation status change log.

Method ‘getActivationHistory’

Get the status change log for given activation and date range.

Request

ActivationHistoryRequest

Response

ActivationHistoryResponse

ActivationHistoryResponse.Item

Integration management

Methods used for managing integration credentials for PowerAuth Server.

Method ‘createIntegration’

Create a new integration with given name, automatically generate credentials for the integration.

Request

CreateIntegrationRequest

Response

CreateIntegrationResponse

Method ‘getIntegrationList’

Get the list of all integrations that are configured on the server instance.

Request

GetIntegrationListRequest

• no attributes

Response

GetIntegrationListResponse

GetIntegrationListResponse.Item

Method ‘removeIntegration’

Remove integration with given ID.

Request

RemoveIntegrationRequest

Response

RemoveIntegrationResponse

Method ‘createCallbackUrl’

Creates a callback URL with given parameters.

Request

CreateCallbackUrlRequest

Response

CreateCallbackUrlResponse

Method ‘getCallbackUrlList’

Get the list of all callbacks for given application.

Request

GetCallbackUrlListRequest

Response

GetCallbackUrlListResponse

GetCallbackUrlListResponse.CallbackUrlList

Method ‘removeCallbackUrl’

Remove callback URL with given ID.

Request

RemoveCallbackUrlRequest

Response

RemoveCallbackUrlResponse

End-To-End Encryption

Method ‘getEciesDecryptor’

Get ECIES decryptor data for request/response decryption on intermediate server.

Request

GetEciesDecryptorRequest

Response

GetEciesDecryptorResponse

Activation versioning

Method ‘startUpgrade’

Upgrade activation to the most recent version supported by the server.

Request

StartUpgradeRequest

Response

StartUpgradeResponse

Method ‘commitUpgrade’

Commint activation upgrade.

Request

CommitUpgradeRequest

Response

CommitUpgradeResponse

Activation recovery

Method ‘createRecoveryCode’

Create a recovery code for user.

Request

CreateRecoveryCodeRequest

Response

CreateRecoveryCodeResponse

CreateRecoveryCodeResponse.Puk

Method confirmRecoveryCode

Confirm a recovery code recieved using recovery postcard.

Request

ConfirmRecoveryCodeRequest

ECIES request should contain following data (as JSON):

• recoveryCode - Recovery code which should be confirmed in this request.

Response

ConfirmRecoveryCodeResponse

ECIES response contains following data (as JSON):

• alreadyConfirmed - Boolean flag which describes whether recovery code was already confirmed before this request.

Method lookupRecoveryCodes

Lookup recovery codes.

Request

LookupRecoveryCodesRequest

Response

LookupRecoveryCodesResponse

LookupRecoveryCodesResponse.Puk

Method revokeRecoveryCodes

Revoke recovery codes.

Request

RevokeRecoveryCodesRequest

Response

RevokeRecoveryCodesResponse

Method recoveryCodeActivation

Create an activation using recovery code. After successfully calling this method, activation is in PENDING_COMMIT state.

If optional activationOtp value is set, then the activation’s OTP validation mode is set to ON_COMMIT. The same OTP value must be later provided in CommitActivation method, to complete the activation.

Request

RecoveryCodeActivationRequest

ECIES request should contain following data (as JSON):

• activationName - Visual representation of the device, for example “Johnny’s iPhone” or “Samsung Galaxy S”.
• devicePublicKey - Represents a public key KEY_DEVICE_PUBLIC (base64-encoded).
• extras - Any client side attributes associated with this activation, like a more detailed information about the client, etc.
• platform - User device platform, e.g. ios, android, hw and unknown.
• deviceInfo - Information about user device, e.g. iPhone12,3.

Response

RevokeRecoveryCodesResponse

ECIES response contains following data (as JSON):

• activationId - Represents a long ACTIVATION_ID that uniquely identifies given activation records.
• serverPublicKey - Public key KEY_SERVER_PUBLIC of the server (base64-encoded).
• ctrData - Initial value for hash-based counter (base64-encoded).
• activationRecovery - Information about activation recovery.
  • recoveryCode - Recovery code which uses 4x5 characters in Base32 encoding separated by a “-“ character.
  • puk - Recovery PUK with unique PUK used as secret for the recovery code.

In case the PUK is invalid and there are still valid PUKs left to try, the error response contains the currentRecoveryPukIndex value in the SOAP fault detail. This value contains information about which PUK should the user re-write next.

Method getRecoveryConfig

Get configuration of activation recovery.

Request

GetRecoveryConfigRequest

Response

GetRecoveryConfigResponse

Method updateRecoveryConfig

Update configuration of activation recovery.

Request

UpdateRecoveryConfigRequest

Response

UpdateRecoveryConfigResponse

Activation management (v2)

Method ‘prepareActivation’ (v2)

Assure a key exchange between PowerAuth Client and PowerAuth Server and prepare the activation with given ID to be committed. Only activations in CREATED state can be prepared. After successfully calling this method, activation is in PENDING_COMMIT state.

Request

PrepareActivationRequest

Response

PrepareActivationResponse

Method ‘createActivation’ (v2)

Create an activation for given user and application, with provided maximum number of failed attempts and expiration timestamp, including a key exchange between PowerAuth Client and PowerAuth Server. Prepare the activation to be committed later. After successfully calling this method, activation is in PENDING_COMMIT state.

Request

CreateActivationRequest

Response

CreateActivationResponse

Token Based Authentication (v2)

Method ‘createToken’ (v2)

Create a new token for the simple token-based authentication.

Request

CreateTokenRequest

Response

CreateTokenResponse

Vault unlocking (v2)

Method ‘vaultUnlock’ (v2)

Get the encrypted vault unlock key upon successful authentication using PowerAuth Signature.

Request

VaultUnlockRequest

Response

VaultUnlockResponse

End-To-End Encryption (v2)

Methods used for establishing a context for end-to-end encryption.

Method ‘getNonPersonalizedEncryptionKey’ (v2)

Establishes a context required for performing a non-personalized (application specific) end-to-end encryption.

Request

GetNonPersonalizedEncryptionKeyRequest

Response

GetNonPersonalizedEncryptionKeyResponse

Method ‘getPersonalizedEncryptionKey’ (v2)

Establishes a context required for performing a personalized (activation specific) end-to-end encryption.

Request

GetPersonalizedEncryptionKeyRequest

Response

GetPersonalizedEncryptionKeyResponse

Used enums

This chapter lists all enums used by PowerAuth Server SOAP service.

• ActivationStatus - Represents the status of activation, one of the following values:
  • CREATED
  • PENDING_COMMIT
  • ACTIVE
  • BLOCKED
  • REMOVED
• ActivationOtpValidation - Represents mode of validation of additional OTP:
  • NONE
  • ON_KEY_EXCHANGE
  • ON_COMMIT
• SignatureType - Represents the type of the signature, one of the following values:
  • POSSESSION
  • KNOWLEDGE
  • BIOMETRY
  • POSSESSION_KNOWLEDGE
  • POSSESSION_BIOMETRY
  • POSSESSION_KNOWLEDGE_BIOMETRY
• RecoveryCodeStatus - Represent status of the recovery code, one of the following values:
  • CREATED
  • ACTIVE
  • BLOCKED
  • REVOKED
• RecoveryPukStatus - Represents status of the recovery PUK, one of the following values:
  • VALID
  • USED
  • INVALID

Used complex types

This chapter lists complex types used by PowerAuth Server SOAP service.

• KeyValueMap - Represents a map for storing key-value entries:
  • entry - list of entries (0..n)
    • key - String-based key
    • value - String-based value