API Reference

PrivakeyCX

public class PrivakeyCX extends Object

Class for handling most of the PrivakeyCX interactions.

Summary

Here is a list of all public methods with a quick description. Further down the page, they are all listed in more detail with any relevant examples. Click on any method to go to its detailed description.

Note: Many of the calls utilize callbacks to return their results. These callbacks are detailed on the callbacks page of this documentation.

Public Constructor

getInstance

public static synchronized PrivakeyCX getInstance()

Creates a singleton instance of PrivakeyCX.

Public Methods

initialize

public void initialize(@NonNull Context context, PrivakeyInitCallback callback)

Initializes the CX library. The internal database is created or initialized, The Retrofit webapi is configured, and a reference to the application context is created. This must be called before any other library calls can be made. After calling this, you can reference the CX library by calling PrivakeyCX.getInstance() in your activities and fragments.

Example

@Override
protected void onCreate(Bundle savedInstanceState) {
     super.onCreate(savedInstanceState);
     PrivakeyCX.getInstance().initialize(getApplicationContext(), new PrivakeyInitCallback() {
         @Override
         public void onInitializeResult(String result) {
             if(Constants.CallbackSuccessStrings.PRIVAKEY_INITIALIZED.equals(result)) {
                 updateAccount();
                 getPendingRequests();
                 //Do other CX logic
             }
         }
     });
}

initialize

public void initialize(@NonNull Context context, PrivakeyInitCallback callback, FailedPasswordCallback failedPasswordCallback, RequestStatusCallback requestStatusCallback, AccountUpdatedCallback accountUpdatedCallback, DeviceUpdatedCallback deviceUpdatedCallback, NewRequestCallback newRequestCallback, GetRequestsCallback getRequestsCallback)

Override of initialize(context, callback), but with individual parameters for specific callbacks.

Several events can happen outside of calling into the library itself, such as receiving a new request notification, or the user's device being revoked from elsewhere. If you want to handle any of these events, you should create a callback and pass it to the library during this initialize call. You may pass null for any of the callbacks to not handle them.

enablePrivakeySessionToken

public void enablePrivakeySessionToken(@NonNull String password, @NonNull String notificationId, @NonNull String notificationFramework, @NonNull String sessionToken, String deviceName, @NonNull String appSpaceGuid, EnablePrivakeyCallback callback)

Enable Privakey on the device.

A user should authenticate with your server, your server will then contact the Privakey CX server to create or retrieve a Privakey account (simple bind). The PrivakeyCX server will return a privakeyId and a sessionToken. This call will generate the required Keypairs and register the device with the CX server. After the device is enrolled and the account has been created the device will be able to process requests for the given App Space.

For more info on the binding process, see Usage Overview.

addAppSpaceCredential

public void addAppSpaceCredential(@NonNull String password, @NonNull String appSpaceGuid, @NonNull String sessionToken, AddAppSpaceCredentialCallback callback)

Use this method to add App Space credentials to an existing Privakey account.

Uses the pin/password to authenticate the device.

This method will generate the keys needed to authenticate requests from the given App Space and upload them to the server.

addAppSpaceCredentialBiometric

public void addAppSpaceCredentialBiometric(@NonNull String appSpaceGuid, @NonNull String sessionToken, String bioPromptText, String bioCancelText, @NonNull Activity activity, AddAppSpaceCredentialCallback callback)

Use this method to add App Space credentials to an existing Privakey account.

Uses biometrics to authenticate the device.

This method will generate the keys needed to authenticate requests from the given App Space and upload them to the server.

isBiometricSensorAvailable

public void isBiometricSensorAvailable(BiometricAvailabilityCallback callback)

Checks to see if biometrics are available for Privakey to use. Only available for Android devices with Marshmallow or later OS. Make sure to call this before doing anything with biometrics.

isBiometricEnabled

public void isBiometricEnabled(BiometricCallback callback)

Checks the status of the biometric key. If it has not been set or has been invalidated, then this method will return a corresponding error message. Only available for Android devices with Marshmallow or later OS.

enableBiometric

public void enableBiometric(@NonNull String password, String bioPromptText, String bioCancelText, Activity activity, BiometricCallback callback)

🚧

Requirements

API: Requires Android API 23+
Device: Device must support Biometrics and have them enabled

Creates a new Key Pair on this device that is Biometric locked. This will allow the CX library to process requests using a biometric instead of a PIN/Password.

disableBiometric

public void disableBiometric(BiometricCallback callback)

🚧

Requirements

API: Requires Android API 23+
Device: Device must support Biometrics and have them enabled

Disables the ability to process requests using a biomimetic on this device. The Biometric Key Pair is deleted from the device.

verifyCurrentPassword

public void verifyCurrentPassword(@NonNull String currentPassword, VerifyCurrentPasswordCallback callback)

Verifies the user's current PIN/password. If the user enters an incorrect PIN/password here, it will count towards their failed attempts, which are potentially limited.

changePassword

public void changePassword(@NonNull String oldPassword, @NonNull String newPassword, ChangePasswordCallback callback)

Changes the PIN/Password used to unlock the Authorization Key Pair for processing strong auth requests.

disablePrivakeyCX

public void disablePrivakeyCX(DisablePrivakeyCallback callback)

Disables Privakey authentications on this device. All local Privakey data will be deleted and the Privakey CX server will be notified that this device can no longer accept Privakey requests.

handlePrivakeyNotification

public void handlePrivakeyNotification(Map<String, String> notificationData)

Processes Privakey specific notifications. Be sure to call this method to forward any Privakey push notifications.

updateDevice

public void updateDevice(@NonNull String notificationFramework, @NonNull String notificationId, String deviceName, UpdateDeviceCallback callback)

Updates some of the device specific information. This call should also be used anytime the Notification ID is updated by a cloud server to continue receiving notifications from the Privakey CX Server.

📘

Cloud Messaging

Use updateDevice to update the NotificationId on the CX server. The notificationId must always be current to continue receiving Cloud messages from the CX Server.

isBound

public void isBound(@NonNull IsBoundCallback callback)

Determines if this device is currently bound to any App Spaces. Useful for E.G. checking during the launch of your app if it's a new user or existing one.

getBoundServices

public void getBoundServices(ServicesCallback callback)

Gets the list of App Spaces this device is currently bound to. In ordinary circumstances, this will only be a single app space.

getCurrentDevice

public void getCurrentDevice(DeviceQueryCallback callback)

Gets the device information, Guid, NotificationId, OS, Status, Notification Framework, name, and creation date for the current device. Use this call to keep your apps account record updated. Use this call to ensure the notificationId on the server is up-to-date with the one assigned to the device.

getDevice

public void getDevice(@NonNull String deviceGuid, DeviceQueryCallback callback)

Gets the device information, Guid, NotificationId, OS, Status, Notification Framework, name, and creation date for the specified device. The device must be bound to the account of the requester.

getDevices

public void getDevices(DeviceStatus[] statuses, DeviceQueryCallback callback)

A device search method. Use this method to return all the devices or select devices based on their status, that are bound to the Privakey account.

revokeAllCredentials

public void revokeAllCredentials(@NonNull String deviceGuid, RevokeAllCredentialsCallback callback)

This will revoke a device from the account. If the device is the current device it will also delete all Privakey CX data from this device. To reuse the device, Devices will have to be re-added via the binding process enablePrivakeySessionToken().

revokeDevice

public void revokeDevice(@NonNull String appSpaceGuid, @NonNull String deviceGuid, RevokeDeviceCallback callback)

Disables and deletes keys used for authorizing requests from the given app space. To authorize requests related to that app space again, the device will have to be re-added via the binding process addAppSpaceCredential().

getRequestByGuid

public void getRequestByGuid(@NonNull String appSpaceGuid, @NonNull String requestGuid, RequestQueryCallback callback)

Gets the Request details for the specified request from the CX server.
If the requested guid is present in the cache, then it will be immediately returned to the RequestQueryCallback parameter.
Finally, any result from making the API call to the CX server will return via the GetRequestsCallback callback of the library.

getRequestsByStatus

public void getRequestsByStatus(@NonNull String appSpaceGuid, @NonNull RequestStatus requestStatus, RequestQueryCallback callback)

Gets all the requests of status requestStatus that are bound to the Privakey account and in the given App Space.
If any requests with the status are present in the cache, then they will be immediately returned to the RequestQueryCallback parameter.
Finally, any result from making the API call to the CX server will return via the GetRequestsCallback callback of the library.

getRequests

public void getRequests(@NonNull String appSpaceGuid, RequestStatus requestStatus, Long beginDate, Long endDate, int limit, RequestQueryCallback callback)

Request search method. This will return all the requests that meet the specified conditions that belong to the Privakey account associated with the given App Space.

NOTE: This does not leverage the GetRequestsCallback and data is always returned via the RequestQueryCallback parameter.

getRequests

public void getRequests(@NonNull String appSpaceGuid, RequestQueryCallback callback, String... requestGuids)

Gets all the requests specified in the requestGuids array. Used to update/retrieve specific requests.
If any of the requested guids are present in the cache, then they will be immediately returned to the RequestQueryCallback parameter.
Finally, any result from making the API call to the CX server will return via the GetRequestsCallback callback of the library.

processRequest

public void processRequest(@NonNull String appSpaceGuid, @NonNull String requestGuid, String password, int selectedButtonIndex, String responseContent, RequestActionCallback callback)

Processes the request associated with requestGuid. This tells the Privakey CX server that you have confirmed an action on the request.

processRequestBiometric

public void processRequestBiometric(@NonNull String appSpaceGuid, @NonNull String requestGuid, int selectedButtonIndex, String responseContent, String bioPromptText, String bioCancelText, Activity activity, RequestActionCallback callback)

Processes the request associated with requestGuid using a biometric. This tells the Privakey CX server that you have confirmed an action on the request.

onDestroy

public void onDestroy()

Perform any final cleanup before the class is destroyed.

requestViewStart

public void requestViewStart(@NonNull Request request)

Starts a request viewed telemetry event.

requestViewEnd

public void requestViewEnd(@NonNull Request request)

Ends a request viewed telemetry event.

requestNotificationReceived

public void requestNotificationReceived(Map<String, String> notificationData)

Records a telemetry event that the given notification was received.

requestNotificationActedOn

public void requestNotificationActedOn(Map<String, String> notificationData)

Records a telemetry event that the given notification was acted on.

recordTelemetry

public void recordTelemetry(@NonNull CXTelemetry telemetry, RecordTelemetryCallback callback)

Records a telemetry event and uploads to the Privakey CX server. This event can be anything, although Privakey CX comes with suggested telemetry events in TelemetryEvent. If the telemetry is unable to be sent (due to network problems, etc), it will be cached until the next telemetry event is sent, at which point any cached telemetries are sent as well.

recordTelemetry

public void recordTelemetry(@NonNull String appSpaceGuid, @NonNull String telemetryEvent, @NonNull Map<String, String> telemetryAttributes, long dateInMS, RecordTelemetryCallback callback)

Records a telemetry event and uploads to the Privakey CX server. This event can be anything, although Privakey CX comes with suggested telemetry events in TelemetryEvent. If the telemetry is unable to be sent (due to network problems, etc), it will be cached until the next telemetry event is sent, at which point any cached telemetries are sent as well.

version

public String version()

Retrieve the library's current version, in the form X.Y.Z

getFailedPasswordCallback

public FailedPasswordCallback getFailedPasswordCallback()

Callback to be executed any time a password/PIN entry fails to be validated. It will also be supplied with the count of the remaining PIN attempts. This is used internally, and exposed for your convenience.

getRequestStatusCallback

public RequestStatusCallback getRequestStatusCallback()

Callback to be executed when a Privakey Request changes status. E.G. when a pending request times out, is canceled or is completed. This is used internally, and exposed for your convenience.

getAccountUpdatedCallback

public AccountUpdatedCallback getAccountUpdatedCallback()

Callback to be executed when the Privakey Account changes status. E.G. when the active account status is changed to revoked or suspended. This is used internally, and exposed for your convenience.

getDeviceUpdatedCallback

public DeviceUpdatedCallback getDeviceUpdatedCallback()

Callback to be executed when the device changes status. E.G. when the active device status is changed to revoked. This is used internally, and exposed for your convenience.

getNewRequestCallback

public NewRequestCallback getNewRequestCallback()

Callback to be executed when a new Privakey Request is created and ready to be acted on. This is used internally, and exposed for your convenience.

getRequestsCallback

public GetRequestsCallback getRequestsCallback()

Callback to be executed when the result from a get request call is made. This includes getRequestByGuid(), getRequestsByStatus(), and getRequests(). Any time a library API endpoint that returns requests is called, it will immediately return any cached data and later return the latest request data via this callback. This is used internally, and exposed for your convenience.

setGetRequestsCallback

public void setGetRequestsCallback(GetRequestsCallback callback)

Sets the library callback for the GetRequestsCallback. Any time a library API endpoint that returns requests is called, it will immediately return any relevant cached data and return the latest request data via this callback. Calling this method will override the GetRequestsCallback passed in during initialize().