Web Services - Methods

This is a 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 v3 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
  • 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
  • updateCallbackUrl
  • getCallbackUrlList
  • removeCallbackUrl
• End-To-End Encryption
  • getEciesDecryptor
• Activation Versioning
  • startUpgrade
  • commitUpgrade
• Activation Recovery
  • createRecoveryCode
  • confirmRecoveryCode
  • lookupRecoveryCodes
  • revokeRecoveryCodes
  • recoveryCodeActivation
  • getRecoveryConfig
  • updateRecoveryConfig
• Activation Flags
  • listActivationFlags
  • addActivationFlags
  • updateActivationFlags
  • removeActivationFlags
• Application Roles
  • listApplicationRoles
  • addApplicationRoles
  • updateApplicationRoles
  • removeApplicationRoles
• Operations
  • createOperation
  • operationDetail
  • findPendingOperationsForUser
  • findAllOperationsForUser
  • findAllOperationsByExternalId
  • cancelOperation
  • approveOperation
  • failApprovalOperation
  • rejectOperation
• Operation Templates
  • createOperationTemplate
  • getAllTemplates
  • getTemplateDetail
  • updateOperationTemplate
  • removeOperationTemplate
• Temporary Keys
  • createTemporaryKey
  • removeTemporaryKey

System status

Methods used for getting the PowerAuth Server system status.

Method ‘getSystemStatus’

Get the server status information.

Request

REST endpoint: POST /rest/v3/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/v3/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/v3/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/v3/application/detail

GetApplicationDetailRequest

Response

GetApplicationDetailResponse

GetApplicationDetailResponse.Version

Method ‘lookupApplicationByAppKey’

Find application using application key.

Request

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

LookupApplicationByAppKeyRequest

Response

LookupApplicationByAppKeyResponse

Method ‘createApplication’

Create a new application with given name.

Request

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

CreateApplicationRequest

Response

CreateApplicationResponse

Method ‘createApplicationVersion’

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

Request

REST endpoint: POST /rest/v3/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/v3/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/v3/application/version/support

SupportApplicationVersionRequest

Response

SupportApplicationVersionResponse

Method ‘getApplicationConfig’

Get application configuration detail.

Request

REST endpoint: POST /rest/v3/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.

Method ‘createApplicationConfig’

Create application configuration.

Request

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

CreateApplicationConfigRequest

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 for OpenID Connect (OIDC) Activation details.

Response

CreateApplicationConfigResponse

Method ‘removeApplicationConfig’

Delete an application configuration.

Request

REST endpoint: POST /rest/v3/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/v3/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 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

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

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.

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

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

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

REST endpoint: POST /rest/v3/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/v3/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/v3/activation/commit

CommitActivationRequest

Response

CommitActivationResponse

Method ‘getActivationStatus’

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

Request

REST endpoint: POST /rest/v3/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/v3/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/v3/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/v3/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/v3/activation/unblock

UnblockActivationRequest

Response

UnblockActivationResponse

Method ‘lookupActivations’

Lookup activations using query parameters.

Request

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

LookupActivationsRequest

Response

LookupActivationsResponse

LookupActivationsResponse.Activation

Method ‘updateStatusForActivations’

Update status for activations identified using their identifiers.

Request

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

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

REST endpoint: POST /rest/v3/signature/verify

VerifySignatureRequest

Response

VerifySignatureResponse

Method ‘verifyECDSASignature’

Verify asymmetric ECDSA signature correctness for given activation and data.

Request

REST endpoint: POST /rest/v3/signature/ecdsa/verify

VerifyECDSASignatureRequest

Response

VerifyECDSASignatureResponse

Method ‘createPersonalizedOfflineSignaturePayload’

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

Request

REST endpoint: POST /rest/v3/signature/offline/personalized/create

CreatePersonalizedOfflineSignaturePayloadRequest

Response

CreatePersonalizedOfflineSignaturePayloadResponse

Method ‘createNonPersonalizedOfflineSignaturePayload’

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

Request

REST endpoint: POST /rest/v3/signature/offline/non-personalized/create

CreateNonPersonalizedOfflineSignaturePayloadRequest

Response

CreateNonPersonalizedOfflineSignaturePayloadResponse

Method ‘verifyOfflineSignature’

Verify off-line signature of provided data.

Request

REST endpoint: POST /rest/v3/signature/offline/verify

VerifyOfflineSignatureRequest

Response

VerifyOfflineSignatureResponse

Token Based Authentication

Method ‘createToken’

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

Request

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

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

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

ValidateTokenRequest

Response

ValidateTokenResponse

Method ‘removeToken’

Remove token with given ID.

Request

REST endpoint: POST /rest/v3/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 Signature.

Request

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

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

REST endpoint: POST /rest/v3/signature/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/v3/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/v3/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/v3/integration/list

GetIntegrationListRequest

• no attributes

Response

GetIntegrationListResponse

GetIntegrationListResponse.Item

Method ‘removeIntegration’

Remove integration with given ID.

Request

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

RemoveIntegrationRequest

Response

RemoveIntegrationResponse

Method ‘createCallbackUrl’

Create a callback URL with given parameters.

Request

REST endpoint: POST /rest/v3/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
• signatureType
• 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]",
    "keyStorePassword": "[keystore password]",
    "keyAlias": "[key alias]",
    "keyPassword": "[key password]",
    "useCustomTrustStore": false,
    "trustStoreLocation": "[truststore resource location]", 
    "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/v3/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
• signatureType
• 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]",
    "keyStorePassword": "[keystore password]",
    "keyAlias": "[key alias]",
    "keyPassword": "[key password]",
    "useCustomTrustStore": false,
    "trustStoreLocation": "[truststore resource location]", 
    "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

UpdateCallbackUrlResponse

Method ‘getCallbackUrlList’

Get the list of all callbacks for given application.

Request

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

GetCallbackUrlListRequest

Response

GetCallbackUrlListResponse

GetCallbackUrlListResponse.CallbackUrlList

Method ‘removeCallbackUrl’

Remove callback URL with given ID.

Request

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

RemoveCallbackUrlRequest

Response

RemoveCallbackUrlResponse

End-To-End Encryption

Method ‘getEciesDecryptor’

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

Request

REST endpoint: POST /rest/v3/ecies/decryptor

GetEciesDecryptorRequest

Response

GetEciesDecryptorResponse

Activation versioning

Method ‘startUpgrade’

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

Upgrade is performed between major activation versions, e.g. upgrade from version 2 to version 3.

Request

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

StartUpgradeRequest

Response

StartUpgradeResponse

Method ‘commitUpgrade’

Commit activation upgrade.

Request

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

CommitUpgradeRequest

Response

CommitUpgradeResponse

Activation recovery

Method ‘createRecoveryCode’

Create a recovery code for user.

Request

REST endpoint: POST /rest/v3/recovery/create

CreateRecoveryCodeRequest

Response

CreateRecoveryCodeResponse

CreateRecoveryCodeResponse.Puk

Method confirmRecoveryCode

Confirm a recovery code received using recovery postcard.

Request

REST endpoint: POST /rest/v3/recovery/confirm

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

REST endpoint: POST /rest/v3/recovery/lookup

LookupRecoveryCodesRequest

Response

LookupRecoveryCodesResponse

LookupRecoveryCodesResponse.Puk

Method revokeRecoveryCodes

Revoke recovery codes.

Request

REST endpoint: POST /rest/v3/recovery/revoke

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

REST endpoint: POST /rest/v3/activation/recovery/create

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 fault detail. This value contains information about which PUK should the user re-write next.

Method getRecoveryConfig

Get configuration of activation recovery.

Request

REST endpoint: POST /rest/v3/recovery/config/detail

GetRecoveryConfigRequest

Response

GetRecoveryConfigResponse

Method updateRecoveryConfig

Update configuration of activation recovery.

Request

REST endpoint: POST /rest/v3/recovery/config/update

UpdateRecoveryConfigRequest

Response

UpdateRecoveryConfigResponse

Activation Flags

Method listActivationFlags

List flags for an activation.

Request

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

ListActivationFlagsRequest

Response

ListActivationFlagsResponse

Method addActivationFlags

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

Request

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

AddActivationFlagsRequest

Response

AddActivationFlagsResponse

Method updateActivationFlags

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

Request

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

UpdateActivationFlagsRequest

Response

UpdateActivationFlagsResponse

Method removeActivationFlags

Remove activation flags for an activation.

Request

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

RemoveActivationFlagsRequest

Response

RemoveActivationFlagsResponse

Application Roles

Method listApplicationRoles

List roles for an application.

Request

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

ListApplicationRolesRequest

Response

ListApplicationRolesResponse

Method addApplicationRoles

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

Request

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

AddApplicationRolesRequest

Response

AddApplicationRolesResponse

Method updateApplicationRoles

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

Request

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

UpdateApplicationRolesRequest

Response

UpdateApplicationRolesResponse

Method removeApplicationRoles

Remove application roles from an activation.

Request

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

RemoveApplicationRolesRequest

Response

RemoveApplicationRolesResponse

Operations

Method ‘createOperation’

Create a new operation based on the operation template.

Request

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

OperationCreateRequest

Response

OperationDetailResponse

Method ‘operationDetail’

Get the operation detail.

Request

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

OperationDetailRequest

Response

OperationDetailResponse

Method ‘findPendingOperationsForUser’

Get the list of pending operations for a user.

Request

REST endpoint: POST /rest/v3/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/v3/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/v3/operation/list/external

OperationExtIdRequest

Response

OperationListResponse

A collection of records with the following structure:

Method ‘cancelOperation’

Cancel an operation.

Request

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

OperationCancelRequest

Response

OperationDetailResponse

Method ‘approveOperation’

Approve an operation.

Request

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

OperationApproveRequest

Response

OperationUserActionResponse

OperationDetailResponse

Method ‘failApproveOperation’

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

Request

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

OperationFailApprovalRequest

Response

OperationUserActionResponse

OperationDetailResponse

Method ‘rejectOperation’

Reject an operation.

Request

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

OperationRejectRequest

Response

OperationUserActionResponse

OperationDetailResponse

Operation Templates

Method ‘createOperationTemplate’

Create an operation template.

Request

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

OperationTemplateCreateRequest

Response

OperationTemplateDetailResponse

Method ‘getAllTemplates’

Get all operation templates.

Request

REST endpoint: POST /rest/v3/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/v3/operation/template/detail

OperationTemplateDetailRequest

Response

OperationTemplateDetailResponse

Method ‘updateOperationTemplate’

Update an operation template.

Request

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

OperationTemplateUpdateRequest

Response

OperationTemplateDetailResponse

Method ‘removeOperationTemplate’

Remove an operation template.

Request

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

OperationTemplateDeleteRequest

Response

empty response

Temporary Keys

Method ‘createTemporaryKey’

Create temporary key pair.

Request

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

TemporaryPublicKeyRequest

TemporaryPublicKeyRequestClaims

Response

TemporaryPublicKeyResponse

TemporaryPublicKeyResponseClaims

Method ‘removeTemporaryKey’

Remove temporary key pair.

Request

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

RemoveTemporaryPublicKeyRequest

Response

RemoveTemporaryPublicKeyResponse

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