Web Services - Methods

This is reference documentation of the methods published by the PowerAuth Server REST services.

The REST service methods can be browsed using Swagger on deployed PowerAuth instance:

• http://localhost:8080/powerauth-java-server/swagger-ui.html

The following v4 methods are published using the service:

• System Status
  • getSystemStatus
  • getErrorCodeList
• Application Management
  • getApplicationList
  • getApplicationDetail
  • lookupApplicationByAppKey
  • createApplication
  • createApplicationVersion
  • unsupportApplicationVersion
  • supportApplicationVersion
  • getApplicationConfig
  • createApplicationConfig
  • removeApplicationConfig
• Activation Management
  • getActivationListForUser
  • initActivation
  • prepareActivation
  • createActivation
  • updateActivationOtp
  • updateActivationName
  • commitActivation
  • confirmActivation
  • getActivationStatus
  • removeActivation
  • blockActivation
  • unblockActivation
  • lookupActivations
  • updateStatusForActivations
• DSA Signature Verification
  • signAsymmetric
  • verifyAsymmetricSignature
• JWT Signature Verification
  • signJwt
  • verifyJwtSignature
• Offline Authentication
  • createNonPersonalizedOfflineAuthPayload
  • createPersonalizedOfflineAuthPayload
  • verifyOfflineAuthentication
• Token-Based Authentication
  • createToken
  • validateToken
  • removeToken
• Vault Unlocking
  • vaultUnlock
• Audit Log
  • getAuditLog
• Activation History
  • getActivationHistory
• Integration Management
  • createIntegration
  • getIntegrationList
  • removeIntegration
• Callback URL Management
  • createCallbackUrl
  • updateCallbackUrl
  • getCallbackUrlList
  • removeCallbackUrl
• End-To-End Encryption
  • extractEncryptor
• Activation Versioning
  • startUpgrade
  • commitUpgrade
• Activation Flags
  • listActivationFlags
  • addActivationFlags
  • updateActivationFlags
  • removeActivationFlags
• Application Roles
  • listApplicationRoles
  • addApplicationRoles
  • updateApplicationRoles
  • removeApplicationRoles
• Operations
  • createOperation
  • operationDetail
  • operationClaim
  • findPendingOperationsForUser
  • findAllOperationsForUser
  • findAllOperationsByExternalId
  • cancelOperation
  • approveOperation
  • failApprovalOperation
  • rejectOperation
• Operation Templates
  • createOperationTemplate
  • getAllTemplates
  • getTemplateDetail
  • updateOperationTemplate
  • removeOperationTemplate
• Dynamic Factor Keys
  • changePassword
  • addBiometry
  • removeBiometry
• Temporary Keys
  • createTemporaryKey
  • removeTemporaryKey
• Telemetry
  • report

System status

Methods used for getting the PowerAuth Server system status.

Method ‘getSystemStatus’

Get the server status information.

Request

REST endpoint: POST /rest/v4/status

GetSystemStatusRequest

• no attributes

Response

GetSystemStatusResponse

Method ‘getErrorCodeList’

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

Request

REST endpoint: POST /rest/v4/error/list

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

REST endpoint: POST /rest/v4/application/list

GetApplicationListRequest

• no attributes

Response

GetApplicationListResponse

GetApplicationListRequest.Application

Method ‘getApplicationDetail’

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

Request

REST endpoint: POST /rest/v4/application/detail

GetApplicationDetailRequest

Response

GetApplicationDetailResponse

GetApplicationDetailResponse.Version

Method ‘lookupApplicationByAppKey’

Find application using application key.

Request

REST endpoint: POST /rest/v4/application/detail/version

LookupApplicationByAppKeyRequest

Response

LookupApplicationByAppKeyResponse

Method ‘createApplication’

Create a new application with given name.

Request

REST endpoint: POST /rest/v4/application/create

CreateApplicationRequest

Response

CreateApplicationResponse

Method ‘createApplicationVersion’

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

Request

REST endpoint: POST /rest/v4/application/version/create

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

REST endpoint: POST /rest/v4/application/version/unsupport

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

REST endpoint: POST /rest/v4/application/version/support

SupportApplicationVersionRequest

Response

SupportApplicationVersionResponse

Method ‘getApplicationConfig’

Get application configuration detail.

Request

REST endpoint: POST /rest/v4/application/config/detail

GetApplicationConfigRequest

Response

GetApplicationConfigResponse

The ApplicationConfigurationItem record contains following parameters:

• String key - configuration key name
• List<Object> values - configuration values

Following configuration keys are expected:

• fido2_attestation_fmt_allowed - list of allowed attestation formats for FIDO2 registrations, unset value means all attestation formats are allowed
• fido2_aaguids_allowed - list of allowed AAGUIDs for FIDO2 registration, unset value means all AAGUIDs are allowed
• fido2_root_ca_certs - list of trusted root CA certificates for certificate validation in PEM format
• oauth2_providers - configuration of OAuth 2.0 providers, see OpenID Connect (OIDC) Activation for details
• activation_transfer - configuration of activation transfer, see Activation Transfer for details
• cryptography_algorithms_supported - list of supported cryptography algorithms, an array of string values, allowed values: EC_P256, EC_P384, EC_P384_ML_L3, EC_P384_ML_L5, when not configured all algorithms are supported
• disable_biometry_unlock_kek_device_private - use a single value true to disable usage of the biometric factor for unlocking the key KEK_DEVICE_PRIVATE

Method ‘createApplicationConfig’

Create application configuration.

Request

REST endpoint: POST /rest/v4/application/config/create

CreateApplicationConfigRequest

The following configuration keys are accepted:

• fido2_attestation_fmt_allowed - list of allowed attestation formats for FIDO2 registrations, unset value means all attestation formats are allowed
• fido2_aaguids_allowed - list of allowed AAGUIDs for FIDO2 registration, unset value means all AAGUIDs are allowed
• fido2_root_ca_certs - list of trusted root CA certificates for certificate validation in PEM format
• oauth2_providers - configuration of OAuth 2.0 providers, see OpenID Connect (OIDC) Activation for details
• activation_transfer - configuration of activation transfer, see Activation Transfer for details
• cryptography_algorithms_supported - list of supported cryptography algorithms, an array of string values, allowed values: EC_P256, EC_P384, EC_P384_ML_L3, EC_P384_ML_L5, when not configured all algorithms are supported
• disable_biometry_unlock_kek_device_private - use a single value true to disable usage of the biometric factor for unlocking the key KEK_DEVICE_PRIVATE

Response

CreateApplicationConfigResponse

Method ‘removeApplicationConfig’

Delete an application configuration.

Request

REST endpoint: POST /rest/v4/application/config/remove

RemoveApplicationConfigRequest

Response

empty response

Activation management

Methods related to activation management.

Method ‘initActivation’

Create (initialize) a new activation for given user and application. If the optional activationOtp parameter is 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

REST endpoint: POST /rest/v4/activation/init

InitActivationRequest

This section describes how to change the activation commit flow:

• By default, the activation follows the state transition diagram described in activation state documentation. The activation gets committed by calling the commit activation endpoint when it is in the PENDING_COMMIT state.
• In case you want the activation to be commited during key exchange, specify the commitPhase parameter with value ON_KEY_EXCHANGE. In this case, the activation transitions from CREATED state directly into ACTIVE state and no separate call is required for performing the activation commit.

In case you require activation OTP validation during activation, specify the activationOtp parameter. The phase when the OTP gets validated is controlled by the commitPhase parameter, either it is checked by default during commit (value ON_COMMIT) or during key exchange (value ON_KEY_EXCHANGE). When the activationOtp parameter is missing, OTP validation is not performed.

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 encrypted 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

REST endpoint: POST /rest/v4/activation/prepare

PrepareActivationRequest

Encrypted request should contain following data (as JSON):

• sharedSecretRequest – Shared secret request including:
  • String algorithm – Shared secret algorithm.
  • String[] encapsulationKeys – Encapsulation keys in order EC, PQC.
• devicePublicKeys – Device public keys including:
  • String ecdsa – ECDSA public key (base64).
  • String mldsa – Optional ML-DSA public key (base64).
• activationName – Visual representation of the device, for example “Johnny’s iPhone” or “Samsung Galaxy S”.
• activationOtp – Optional activation OTP for confirmation.
• externalId – Optional external ID associated with activation.
• platform – User device platform, e.g. ios, android, hw and unknown.
• deviceInfo – Information about user device, e.g. iPhone12,3.
• extras – Any client side attributes associated with this activation, like a more detailed information about the client, etc.

Response

PrepareActivationResponse

Encrypted response contains following data (as JSON):

• sharedSecretResponse – Shared secret response including:
  • String salt - Salt used by KMAC algorithm during shared secret derivation.
  • String[] encapsulatedKeys - Encapsulated keys in order EC, PQC.
• serverPublicKeys – Server public keys including:
  • String ecdsa - ECDSA public key (base64).
  • String mldsa - Optional ML-DSA public key (base64).
• activationId – Long numeric activation identifier
• ctrData – Initial counter data for hashing (base64)

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

REST endpoint: POST /rest/v4/activation/create

CreateActivationRequest

Encrypted request should contain following data (as JSON):

• sharedSecretRequest – Shared secret request including:
  • String algorithm – Shared secret algorithm.
  • String[] encapsulationKeys – Encapsulation keys in order EC, PQC.
• devicePublicKeys – Device public keys including:
  • String ecdsa – ECDSA public key (base64).
  • String mldsa – Optional ML-DSA public key (base64).
• activationName – Visual representation of the device, for example “Johnny’s iPhone” or “Samsung Galaxy S”.
• activationOtp – Optional activation OTP for confirmation.
• externalId – Optional external ID associated with activation.
• platform – User device platform, e.g. ios, android, hw and unknown.
• deviceInfo – Information about user device, e.g. iPhone12,3.
• extras – Any client side attributes associated with this activation, like a more detailed information about the client, etc.

Response

CreateActivationResponse

Encrypted response contains following data (as JSON):

• sharedSecretResponse – Shared secret response including:
  • String salt - Salt used by KMAC algorithm during shared secret derivation.
  • String[] encapsulatedKeys - Encapsulated keys in order EC, PQC.
• serverPublicKeys – Server public keys including:
  • String ecdsa - ECDSA public key (base64).
  • String mldsa - Optional ML-DSA public key (base64).
• activationId – Long numeric activation identifier.
• ctrData – Initial counter data for hashing (base64).

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

REST endpoint: POST /rest/v4/activation/otp/update

UpdateActivationOtpRequest

Response

UpdateActivationOtpResponse

Method ‘updateActivationName’

Update activation name for activation with given ID. No allowed for activation in status CREATED, REMOVED, or BLOCKED.

After successful, activation name is updated.

Request

REST endpoint: POST /rest/v4/activation/name/update

UpdateActivationNameRequest

Response

UpdateActivationNameResponse

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

REST endpoint: POST /rest/v4/activation/commit

CommitActivationRequest

Response

CommitActivationResponse

Method ‘confirmActivation’

Confirm activation with given ID.

This method is used to confirm activations from the mobile SDK and set up biometry after the biometry setup is finished on the mobile device.

Request

REST endpoint: POST /rest/v4/activation/confirm

ConfirmActivationRequest

Response

empty response

Method ‘getActivationStatus’

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

Request

REST endpoint: POST /rest/v4/activation/status

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

REST endpoint: POST /rest/v4/activation/remove

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

REST endpoint: POST /rest/v4/activation/list

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

REST endpoint: POST /rest/v4/activation/block

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

REST endpoint: POST /rest/v4/activation/unblock

UnblockActivationRequest

Response

UnblockActivationResponse

Method ‘lookupActivations’

Lookup activations using query parameters.

Request

REST endpoint: POST /rest/v4/activation/lookup

LookupActivationsRequest

Response

LookupActivationsResponse

LookupActivationsResponse.Activation

Method ‘updateStatusForActivations’

Update status for activations identified using their identifiers.

Request

REST endpoint: POST /rest/v4/activation/status/update

UpdateStatusForActivationsRequest

Response

UpdateStatusForActivationsResponse

DSA Signature Verification

Methods related to DSA signature verification.

Method ‘signAsymmetric’

Sign data using available asymmetric signature algorithms.

Request

REST endpoint: POST /rest/v4/dsa/sign

SignAsymmetricRequest

Response

SignAsymmetricResponse

Method ‘verifyAsymmetricSignature’

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

Request

REST endpoint: POST /rest/v4/dsa/verify

VerifyAsymmetricSignatureRequest

Response

VerifyAsymmetricSignatureResponse

JWT Signature Verification

Methods related to JWT signature verification.

Method ‘signJwt’

Sign data using JWT signature algorithm.

Request

REST endpoint: POST /rest/v4/jwt/sign

SignJwtRequest

Response

SignJwtResponse

Method ‘verifyJwtSignature’

Verify JWT signature.

Request

REST endpoint: POST /rest/v4/jwt/verify

VerifyJwtSignatureRequest

Response

VerifyJwtSignatureResponse

Offline Authentication

Methods related to offline authentication code validation.

Method ‘createNonPersonalizedOfflineAuthPayload’

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

Request

REST endpoint: POST /rest/v4/auth/offline/non-personalized/create

CreateNonPersonalizedOfflineAuthPayloadRequest

Response

CreateNonPersonalizedOfflineAuthPayloadResponse

Method ‘createPersonalizedOfflineAuthPayload’

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

Request

REST endpoint: POST /rest/v4/auth/offline/personalized/create

CreatePersonalizedOfflineAuthPayloadRequest

Response

CreatePersonalizedOfflineAuthPayloadResponse

Method ‘verifyOfflineAuthentication’

Verify offline authentication code for provided data.

Request

REST endpoint: POST /rest/v4/auth/offline/verify

VerifyOfflineAuthenticationRequest

Response

VerifyOfflineAuthenticationResponse

Token-Based Authentication

Method ‘createToken’

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

Request

REST endpoint: POST /rest/v4/token/create

CreateTokenRequest

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

{}

Response

CreateTokenResponse

AEAD 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

REST endpoint: POST /rest/v4/token/validate

ValidateTokenRequest

Response

ValidateTokenResponse

Method ‘removeToken’

Remove token with given ID.

Request

REST endpoint: POST /rest/v4/token/remove

RemoveTokenRequest

Response

RemoveTokenResponse

Vault unlocking

Methods related to secure vault.

Method ‘vaultUnlock’

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

Request

REST endpoint: POST /rest/v4/vault/unlock

VaultUnlockRequest

AEAD request should contain following data:

{
    "keyIdentifier": "...",
    "reason": "..."
}

Following key identifiers are supported:

• KEK_DEVICE_PRIVATE - key encryption key for the device private key
• KDK_APP_VAULT_KNOWLEDGE - key encryption key for vault used after 2FA with a knowledge factor
• KDK_APP_VAULT_2FA - key encryption key for vault used after any 2FA authentication

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

AEAD response contains following data (example):

{
    "vaultEncryptionKey": "..."
}

Audit Log

Methods related to auditing.

Method ‘getAuditLog’

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

Request

REST endpoint: POST /rest/v4/audit/list

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

REST endpoint: POST /rest/v4/activation/history

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

REST endpoint: POST /rest/v4/integration/create

CreateIntegrationRequest

Response

CreateIntegrationResponse

Method ‘getIntegrationList’

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

Request

REST endpoint: POST /rest/v4/integration/list

GetIntegrationListRequest

• no attributes

Response

GetIntegrationListResponse

GetIntegrationListResponse.Item

Method ‘removeIntegration’

Remove integration with given ID.

Request

REST endpoint: POST /rest/v4/integration/remove

RemoveIntegrationRequest

Response

RemoveIntegrationResponse

Method ‘createCallbackUrl’

Create a callback URL with given parameters.

Request

REST endpoint: POST /rest/v4/application/callback/create

CreateCallbackUrlRequest

When creating a callback URL of type ACTIVATION_STATUS_CHANGE, following attributes can be used:

• userId
• activationName
• deviceInfo
• platform
• protocol
• activationFlags
• activationStatus
• blockedReason
• applicationId

When creating a callback URL of type OPERATION_STATUS_CHANGE, following attributes can be used:

• userId
• applications
• operationType
• parameters
• additionalData
• activationFlag
• status
• data
• failureCount
• maxFailureCount
• authenticationCodeType
• externalId
• timestampCreated
• timestampExpires
• timestampFinalized

The authentication parameter contains a JSON-based configuration for client TLS certificate and HTTP basic authentication:

{
  "certificate": {
    "enabled": false,
    "useCustomKeyStore": false,
    "keyStoreLocation": "[keystore resource location]",
    "keyStoreContent": "[keystore content encoded in Base64]",
    "keyStorePassword": "[keystore password]",
    "keyAlias": "[key alias]",
    "keyPassword": "[key password]",
    "useCustomTrustStore": false,
    "trustStoreLocation": "[truststore resource location]",
    "trustStoreContent": "[truststore content encoded in Base64]",
    "trustStorePassword": "[truststore password]"
  },
  "httpBasic": {
    "enabled": false,
    "username": "[HTTP basic authentication username]",
    "password": "[HTTP basic authentication password]"
  },
  "oauth2": {
    "enabled": false,
    "clientId": "[OAuth2 client ID]",
    "clientSecret": "[OAuth2 client secret]",
    "tokenUri": "[OAuth2 token URI]",
    "scope": "[OAuth2 scope]"
  }
}

Response

CreateCallbackUrlResponse

Method ‘updateCallbackUrl’

Update a callback URL with given parameters.

Request

REST endpoint: POST /rest/v4/application/callback/update

UpdateCallbackUrlRequest

When configuring a callback URL of type ACTIVATION_STATUS_CHANGE, following attributes can be used:

• userId
• activationName
• deviceInfo
• platform
• protocol
• activationFlags
• activationStatus
• blockedReason
• applicationId

When configuring a callback URL of type OPERATION_STATUS_CHANGE, following attributes can be used:

• userId
• applications
• operationType
• parameters
• additionalData
• activationFlag
• status
• data
• failureCount
• maxFailureCount
• authenticationCodeType
• externalId
• timestampCreated
• timestampExpires
• timestampFinalized

The authentication parameter contains a JSON-based configuration for client TLS certificate and HTTP basic authentication:

{
  "certificate": {
    "enabled": false,
    "useCustomKeyStore": false,
    "keyStoreLocation": "[keystore resource location]",
    "keyStoreContent": "[keystore content encoded in Base64]",
    "keyStorePassword": "[keystore password]",
    "keyAlias": "[key alias]",
    "keyPassword": "[key password]",
    "useCustomTrustStore": false,
    "trustStoreLocation": "[truststore resource location]",
    "trustStoreContent": "[truststore content encoded in Base64]",
    "trustStorePassword": "[truststore password]"
  },
  "httpBasic": {
    "enabled": false,
    "username": "[HTTP basic authentication username]",
    "password": "[HTTP basic authentication password]"
  },
  "oauth2": {
    "enabled": false,
    "clientId": "[OAuth2 client ID]",
    "clientSecret": "[OAuth2 client secret]",
    "tokenUri": "[OAuth2 token URI]",
    "scope": "[OAuth2 scope]"
  }
}

In case you do not want to modify the already set keyStoreContent or trustStoreContent, send a null value in request. For removing the existing keyStoreContent or trustStoreContent use an empty string.

Response

UpdateCallbackUrlResponse

Method ‘getCallbackUrlList’

Get the list of all callbacks for given application.

Request

REST endpoint: POST /rest/v4/application/callback/list

GetCallbackUrlListRequest

Response

GetCallbackUrlListResponse

GetCallbackUrlListResponse.CallbackUrlList

Method ‘removeCallbackUrl’

Remove callback URL with given ID.

Request

REST endpoint: POST /rest/v4/application/callback/remove

RemoveCallbackUrlRequest

Response

RemoveCallbackUrlResponse

End-To-End Encryption

Method ‘extractEncryptor’

Extract the encryptor data for request/response encryption and decryption on intermediate server.

Request

REST endpoint: POST /rest/v4/encryptor

ExtractEncryptorRequest

Response

ExtractEncryptorResponse

Activation versioning

Method ‘startUpgrade’

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

Upgrade is performed between major activation versions, upgrade from version 3 to version 4.

Request

REST endpoint: POST /rest/v4/upgrade/start

StartUpgradeRequest

Response

StartUpgradeResponse

Method ‘commitUpgrade’

Commit activation upgrade.

Request

REST endpoint: POST /rest/v4/upgrade/commit

CommitUpgradeRequest

Response

CommitUpgradeResponse

Activation Flags

Method listActivationFlags

List flags for an activation.

Request

REST endpoint: POST /rest/v4/activation/flags/list

ListActivationFlagsRequest

Response

ListActivationFlagsResponse

Method addActivationFlags

Add activation flags to an activation. Duplicate flags are ignored.

Request

REST endpoint: POST /rest/v4/activation/flags/create

AddActivationFlagsRequest

Response

AddActivationFlagsResponse

Method updateActivationFlags

Update activation flags to an activation. Existing flags are removed.

Request

REST endpoint: POST /rest/v4/activation/flags/update

UpdateActivationFlagsRequest

Response

UpdateActivationFlagsResponse

Method removeActivationFlags

Remove activation flags for an activation.

Request

REST endpoint: POST /rest/v4/activation/flags/remove

RemoveActivationFlagsRequest

Response

RemoveActivationFlagsResponse

Application Roles

Method listApplicationRoles

List roles for an application.

Request

REST endpoint: POST /rest/v4/application/roles/list

ListApplicationRolesRequest

Response

ListApplicationRolesResponse

Method addApplicationRoles

Add application roles to an application. Duplicate roles are ignored.

Request

REST endpoint: POST /rest/v4/application/roles/create

AddApplicationRolesRequest

Response

AddApplicationRolesResponse

Method updateApplicationRoles

Update application roles assigned to an application. Existing roles are removed.

Request

REST endpoint: POST /rest/v4/application/roles/update

UpdateApplicationRolesRequest

Response

UpdateApplicationRolesResponse

Method removeApplicationRoles

Remove application roles from an application.

Request

REST endpoint: POST /rest/v4/application/roles/remove

RemoveApplicationRolesRequest

Response

RemoveApplicationRolesResponse

Operations

Method ‘createOperation’

Create a new operation based on the operation template.

Request

REST endpoint: POST /rest/v4/operation/create

OperationCreateRequest

Response

OperationDetailResponse

Method ‘operationDetail’

Get the operation detail.

Request

REST endpoint: POST /rest/v4/operation/detail

OperationDetailRequest

Response

OperationDetailResponse

Method ‘operationClaim’

Claim the operation for a user.

Request

REST endpoint: POST /rest/v4/operation/claim

OperationClaimRequest

Response

OperationDetailResponse

Method ‘findPendingOperationsForUser’

Get the list of pending operations for a user.

Request

REST endpoint: POST /rest/v4/operation/list/pending

OperationListForUserRequest

Response

OperationListResponse

A collection of records with the following structure:

Method ‘findAllOperationsForUser’

Get the list of all operations for a user.

Request

REST endpoint: POST /rest/v4/operation/list

OperationListForUserRequest

Response

OperationListResponse

A collection of records with the following structure:

Method ‘findAllOperationsByExternalID’

Get the list of operations by external ID.

Request

REST endpoint: POST /rest/v4/operation/list/external

OperationExtIdRequest

Response

OperationListResponse

A collection of records with the following structure:

Method ‘findAllOperationsForUser’

Get the list of all operations for a user.

Request

REST endpoint: POST /rest/v4/operation/list

OperationListForUserRequest

Response

OperationListResponse

A collection of records with the following structure:

Method ‘cancelOperation’

Cancel an operation.

Request

REST endpoint: POST /rest/v4/operation/cancel

OperationCancelRequest

Response

OperationDetailResponse

Method ‘approveOperation’

Approve an operation.

Request

REST endpoint: POST /rest/v4/operation/approve

OperationApproveRequest

Response

OperationUserActionResponse

Method ‘failApproveOperation’

Fail approval of an operation to increment the failed attempt counter by one.

Request

REST endpoint: POST /rest/v4/operation/approve/fail

OperationFailApprovalRequest

Response

OperationUserActionResponse

Method ‘rejectOperation’

Reject an operation.

Request

REST endpoint: POST /rest/v4/operation/reject

OperationRejectRequest

Response

OperationUserActionResponse

Operation Templates

Method ‘createOperationTemplate’

Create an operation template.

Request

REST endpoint: POST /rest/v4/operation/template/create

OperationTemplateCreateRequest

Response

OperationTemplateDetailResponse

Method ‘getAllTemplates’

Get all operation templates.

Request

REST endpoint: POST /rest/v4/operation/template/list

Empty request body

Response

OperationTemplateListResponse

Collection of items with the following structure:

Method ‘getTemplateDetail’

Get an operation template detail.

Request

REST endpoint: POST /rest/v4/operation/template/detail

OperationTemplateDetailRequest

Response

OperationTemplateDetailResponse

Method ‘updateOperationTemplate’

Update an operation template.

Request

REST endpoint: POST /rest/v4/operation/template/update

OperationTemplateUpdateRequest

Response

OperationTemplateDetailResponse

Method ‘removeOperationTemplate’

Remove an operation template.

Request

REST endpoint: POST /rest/v4/operation/template/remove

OperationTemplateDeleteRequest

Response

empty response

Dynamic Factor Keys

Method ‘changePassword’

Change the password-related dynamic factor key.

Request

REST endpoint: POST /rest/v4/password/change

ChangePasswordRequest

Response

ChangePasswordResponse

Method ‘addBiometry’

Set up the biometry-related dynamic factor key.

Request

REST endpoint: POST /rest/v4/biometry/add

AddBiometryRequest

Response

AddBiometryResponse

Method ‘removeBiometry’

Remove the biometry-related dynamic factor key.

Request

REST endpoint: POST /rest/v4/biometry/remove

RemoveBiometryRequest

Response

Empty response

Temporary Keys

Method ‘createTemporaryKey’

Create temporary key pair.

Request

REST endpoint: POST /rest/v4/keystore/create

TemporaryPublicKeyRequest

TemporaryPublicKeyRequestClaims

Response

TemporaryPublicKeyResponse

TemporaryPublicKeyResponseClaims

Method ‘removeTemporaryKey’

Remove the temporary key pair.

Request

REST endpoint: POST /rest/v4/keystore/remove

RemoveTemporaryPublicKeyRequest

Response

RemoveTemporaryPublicKeyResponse

Telemetry

Method report

Generate a telemetry report.

Request

REST endpoint: POST /rest/v4/telemetry/report

TelemetryReportRequest

Response

TelemetryReportResponse

Used enums

This chapter lists all enums used by PowerAuth Server services.

• 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 (deprecated):
  • NONE
  • ON_KEY_EXCHANGE
  • ON_COMMIT
• CommitPhase - Specifies when activation is committed:
  • ON_COMMIT (default) - activation is committed in the PENDING_COMMIT state
  • ON_KEY_EXCHANGE - activation is committed during key exchange
• AuthenticationCodeType - Represents the type of the authentication code, one of the following values:
  • POSSESSION
  • KNOWLEDGE
  • BIOMETRY
  • POSSESSION_KNOWLEDGE
  • POSSESSION_BIOMETRY
  • POSSESSION_KNOWLEDGE_BIOMETRY
• OperationStatus - Represents the possible operation status
  • PENDING
  • CANCELED
  • EXPIRED
  • APPROVED
  • REJECTED
  • FAILED
• UserActionResult - Represents the result of the user action when approving operation.
  • APPROVED
  • APPROVAL_FAILED
  • REJECTED
  • REJECT_FAILED
  • OPERATION_FAILED

Used complex types

This chapter lists complex types used by PowerAuth Server services.

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