API Reference

PrivakeyCX

public class PrivakeyCX : NSObject

Swift API library for interacting with the PrivakeyCX server.

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 methods utilize completion handlers to return their results, due to their asynchronous nature. For more info on this, see the Swift documentation on Closures.

Public Constructors
init()

Initializes Privakey with the default CX API, CoreData data service, Apple’s Local Authentication Context for biometry, and the default Pin Entry Manager.
init(apiService: APIService, dataService: DataManager, localAuthenticationService: LocalAuthenticationManager, pinEntriesService: PinEntriesManager)

Initializes Privakey with the given custom services to facilitate testing and customization using dependency injection.
Public Properties
delegate?A PrivakeyCXDelegate for handling various asynchronous actions.
uiDelegate?A PinEntriesManagerUIDelegate for handling Pin attempts left in the UI.
Public Methods
getVersion() -> String
Get the version of the library.
enablePrivakey( password: String, notificationId: String, notificationFramework: String, deviceName: String, sessionToken: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )
Use this method to register an account and tokenize the device after performing a simple bind.
addAppSpaceCredential( password: String, appSpaceGuid: String, sessionToken: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )
Adds a new AppSpace credential to an existing Privakey account using PIN. This is very rarely used.
addAppSpaceCredentialBiometric`( appSpaceGuid: String, sessionToken: String, bioPromptText: String?, completion: @escaping ( success: Bool?, error: Error? ) -> Void )
Adds a new AppSpace credential to an existing Privakey account using biometrics. This is very rarely used.
isBiometricSensorAvailable( completion: @escaping ( _ isAvailable: Bool, _ message: String ) -> Void )
Queries the system to see if a biometric sensor is available and ready for use.
isBiometricEnabled( completion: @escaping ( _ success: Bool, _ error: Error? ) -> Void )
Queries the system to see if the user has explicitly enabled biometric authentication.
enableBiometric( password: String, bioPromptText: String?, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )
Enables the use of biometric for processing requests. E.G. Touch ID or Face ID.
isBound( completion: @escaping ( _ isBound: Bool, _ error: Error? ) -> Void )
Determines if this device is currently bound to any App Spaces.
disableBiometric( completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )
Disables the use of biometrics for processing requests.
changePassword( oldPassword: String, newPassword: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )
Changes the PIN/Password used for processing strong auth requests.
validatePassword( password: String )
Validates an entered PIN/Password.
disablePrivakeyCX( completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )
Removes the Privakey Account from the device and notifies the CX server that the device is no longer Privakey enabled.
revokeDevice( appSpaceGuid: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )
Removes the device from the Privakey Account. This device will no longer be able to process requests until it is registered to the Privakey account again.
getDevices( status: DeviceStatus, completion: @escaping ( _ devices: [PrivakeyDevice]?, _ error: Error? ) -> Void )
Returns an Array of Devices matching the requested DeviceStatus.
getCurrentDevice( completion: @escaping ( _ device: PrivakeyDevice?, _ error: Error? ) -> Void )
Gets the current device data from the local cache.
getDevice( deviceGuid: String, completion: @escaping ( _ device: PrivakeyDevice?, _ account: PrivakeyAccount?, _ error: Error? ) -> Void )
Gets the device data for the requested device. The device must be owned by the same Privakey account making the request.
updateDevice( name: String, notificationFramework: String, notificationId: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )
Updates some of the device data on the CX server. This method has to be called when the notification Id changes to continue to receive push notifications.
getRequestByGuid( appSpaceGuid: String, requestGuid: String, completion: @escaping ( _ request: PrivakeyRequest?, _ error: Error? ) -> Void )
Returns the Request data for the specified request. The request must be bound to the Privakey account making the call.
getRequestsByStatus( appSpaceGuid: String, requestStatus: RequestStatus, completion: @escaping ( _ requests: [PrivakeyRequest]?, _ error: Error? ) -> Void )
Get all requests of a certain status that belong to this account. This method is shorthand for the other method, getRequests().
getRequests( appSpaceGuid: String, requestStatus: RequestStatus?, beginDate: Date?, endDate: Date?, limit: Int?, completion: @escaping ( _ requests: [PKRequest]?, _ error: Error? ) -> Void )
A generic Request search. Returns an Array of requests based on the parameters supplied.
processRequest( appSpaceGuid: String, requestGuid: String, password: String?, selectedButtonIndex: Int, responseContent: String?, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )
Processes a request using the account PIN/Password. password is only required if this is a strong auth request.
processRequestBiometric( appSpaceGuid: String, requestGuid: String, selectedButtonIndex: Int, responseContent: String?, biometricAuthReason: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )
Processes a request using the account registered Biometric.
requestNotificationActedOn( notificationUserInfo: [AnyHashable: Any] )
Uploads telemetry data for the event a request notification is clicked.
requestViewStart( request: PrivakeyRequest )
Initiates the process of uploading a request viewed telemetry event.
requestViewEnd( request: PrivakeyRequest )
Completes the process of uploading a request viewed telemetry event.
handlePrivakeyNotification( notificationUserInfo: [AnyHashable : Any], completion: @escaping ( _ didRevokeDevice: Bool ) -> Void )
Forward any received Privakey push notifications so they can be processed.
checkStatus( completion: @escaping ( _ didRevokeDevice: Bool, _ didSuspendAccount: Bool ) -> Void )
Checks if the current device or associated account status has changed and handles it appropriately.

Public Constructors

init

public convenience override init ()

Initializes Privakey with the default CX API, CoreData data service, Apple’s Local Authentication Context for biometry, and the default Pin Entry Manager.

public init ( apiService: APIService, dataService: DataManager, localAuthenticationService: LocalAuthenticationManager, pinEntriesService: PinEntriesManager )

Initializes Privakey with the given custom services to facilitate testing and customization using dependency injection.

Parameters
apiServiceThe service to connect to the CX API. Default is PrivakeyCXAPIService().
dataServiceThe data service for Privakey to persist data. Default is CoreDataStack().
localAuthenticationServiceThe Authentication Manager for handling biometrics. Default is LocalAuthenticationManager().
pinEntriesServiceThe manager for handling invalid pin attempts. Default is PinEntriesManager().

Public Properties

delegate

public weak var delegate : PrivakeyCXDelegate?

Assign a PrivakeyCXDelegate to this property to handle certain asynchronous events. For more info, see the Delegates page.

uiDelegate

public weak var uiDelegate: PinEntriesManagerUIDelegate?

Assign a delegate to this property to update the UI for failed PIN entry events. We recommend updating your view to let the user know how many PIN entry attempts they have remaining, and adding an additional warning if they only have 1 attempt remaining, as they will be revoked if they fail at that point.

Public Methods

getVersion

public func getVersion () -> String

Returns the current version of the library, in the form X.Y.Z


enablePrivakey

public func enablePrivakey ( password: String, notificationId: String, notificationFramework: String, deviceName: String, appSpaceGuid: String, sessionToken: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

Enable Privakey for an account. Keys are generated for use with Privakey, binding this device to the user's Privakey account.

A user should authenticate with your server, your server will then contact the CX Server to create or retrieve a Privakey account. The CX 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.

Parameters
passwordThe PIN/Password used to secure the private key for making strong authorizations.
notificationIdThe device notification Id. The ID that is used for the device to receive remote push notifications.
notificationFrameworkThe framework being used to receive push notifications. This value should match the key used by the CX Comm server for choosing which framework to send notifications. eg. Firebase, APNS, etc.
deviceNameFriendly human readable device identifier or nickname.
appSpaceGuidIdentifier of the App Space being bound to this device.
sessionTokenA token used by the server to confirm the device being tokenized is the same device that authenticated with your server. This value should be passed back to the device after a successful authentication with your server.
completionCompletion handler with these params:
success - True if successful.
error - nil if successful, otherwise an error object.

addAppSpaceCredential

public func addAppSpaceCredential ( password: String, appSpaceGuid: String, sessionToken: String, completion: @escaping ( _ success: Bool?, _ error: Error?) -> Void )

Add an additional credential for a new AppSpace. For your first AppSpace, you should call enablePrivakey() instead of this.

Parameters
passwordThe PIN/Password used to secure the private key for making strong authorizations.
appSpaceGuidGUID of the new App Space being added
sessionTokenA token used by the server to confirm the device being tokenized is the same device that authenticated with your server. This value should be passed back to the device after a successful authentication with your server.
completionCompletion handler with these params:
success: True if successful.
error: nil if successful, otherwise an error object.

addAppSpaceCredentialBiometric

public func addAppSpaceCredentialBiometric ( appSpaceGuid: String, sessionToken: String, bioPromptText: String?, completion: @escaping ( _ success: Bool?, _ error: Error?) -> Void )

Add an additional credential for a new AppSpace. This function uses the user's biometrics instead of a PIN/password. For your first AppSpace, you should call enablePrivakey().

Parameters
appSpaceGuidGUID of the new App Space being added
sessionTokenA token used by the server to confirm the device being tokenized is the same device that authenticated with your server. This value should be passed back to the device after a successful authentication with your server.
bioPromptTextText to present the user as the reason for capturing their biometrics. Defaults to "Privakey will use <Touch ID/Face ID> during approvals that require a strong assertion of your intent."
completionCompletion handler with these params:
success: True if successful.
error: nil if successful, otherwise an error object.

isBiometricSensorAvailable

public func isBiometricSensorAvailable ( completion: @escaping ( _ isAvailable: Bool, _ message: String ) -> Void )

Queries the system to see if a biometric sensor is available and ready for use.

Parameters
completionCompletion handler with these params:
isAvailable: True if a sensor is available.
message: "Biometrics Available" if a sensor is available, otherwise an error message.

isBiometricEnabled

public func isBiometricEnabled ( completion: @escaping ( _ success: Bool, _ error: Error? ) -> Void )

Queries the system to see if a user has explicitly enabled biometric authentication for the implementing app.

Parameters
completionCompletion handler with these params:
success: True if successful.
error: nil if successful, otherwise an error object.

enableBiometric

public func enableBiometric ( password: String, bioPromptText: String?, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

Enables PrivakeyCX to accept biometrics for authentications. E.G. Touch ID or Face ID.

Parameters
passwordThe PIN/Password used to secure the private key for making strong authorizations.
bioPromptTextText to present the user as the reason for capturing their biometrics. Defaults to "Privakey will use <Touch ID/Face ID> during approvals that require a strong assertion of your intent."
completionCompletion handler with these params:
success - True if successful.
error - nil if successful, otherwise an error object.

isBound

public func isBound ( completion: @escaping ( _ isBound: Bool, _ error: Error? ) -> Void )

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.

Parameters
completionCompletion handler with these params:
isBound - Whether user is bound or not.
error - nil if successful, otherwise an error object.

disableBiometric

public func disableBiometric ( completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

Disabled PrivakeyCX support for biometrics (Touch ID/Face ID). Only a PIN/password will be allowed to authorize requests.

Parameters
completionCompletion handler with these params:
success - True if successful.
error - nil if successful, otherwise an error object.

changePassword

public func changePassword ( oldPassword: String, newPassword: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

Allows a user to change their PIN/password.

Parameters
oldPasswordThe current password used to process strong authorization requests.
newPasswordThe password to replace the oldPassword.
completionCompletion handler with these params:
success - True if successful.
error - nil if successful, otherwise an error object.

validatePassword

public func validatePassword ( password: String ) -> Bool

Validates an entered PIN/Password. Invalid PIN attempts are protected by the Pin Entries Manager which disables the device after the max attempts have been used.

Parameters
passwordThe password to validate.
Returns
BoolTrue if the password was correct.

disablePrivakeyCX

public func disablePrivakeyCX ( completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

Deletes all the PrivakeyCX data and notifies the server that PrivakeyCX has been disabled for this device.

Parameters
completionCompletion handler with these params:
success - True if successful.
error - nil if successful, otherwise an error object.

revokeDevice

public func revokeDevice ( appSpaceGuid: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

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.

appSpaceGuidIdentifier of the App Space credentials to remove.
completionCompletion handler with these params:
success - True if successful.
error - nil if successful, otherwise an error object.

getDevices

public func getDevices ( status: DeviceStatus, completion: @escaping (_ devices: [PrivakeyDevice]?, _ error: Error? ) -> Void )

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

Parameters
statusThe status of devices that are to be returned.
completionCompletion handler with these params:
devices - The fetched devices.
error - nil if successful, otherwise an error object.

getCurrentDevice

public func getCurrentDevice ( completion: @escaping ( _ device: PrivakeyDevice?, _ error: Error? ) -> Void )

Gets the locally cached device information.

Parameters
completionCompletion handler with these params:
device - The current device.
error - nil if successful, otherwise an error object.

getDevice

public func getDevice ( deviceGuid: String, completion: @escaping ( _ device: PrivakeyDevice?, _ account: PrivakeyAccount?, _ error: Error? ) -> Void )

Gets information for a specific device. The specified device must belong to the same account as the calling device.

Parameters
deviceGuidThe device identifier of the device whose data is being requested.
completionCompletion handler with these params:
device - The fetched device.
account - The account that the device is associated to.
error - nil if successful, otherwise an error object.

updateDevice

public func updateDevice ( name: String, notificationFramework: String, notificationId: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

Updates some of the device specific information. You are required to call this method when your app’s notification token or ID changes to continue receiving notifications from the CX Server.

📘

Push Notifications

Use updateDevice() to update the NotificationId on the CX server. The notificationId must always be current to continue receiving push notifications from the CX Server.

Parameters
nameFriendly human readable device identifier.
notificationFrameworkThe framework being used to receive push notifications. This value should match the key used by the CX Comm server for choosing which framework to send notifications. eg. Firebase, APNS, etc.
notificationIdThe device notification Id. The ID that is used for the device to receive push notifications.
completionCompletion handler with these params:
success - True if successful.
error - nil if successful, otherwise an error object.

getRequestByGuid

public func getRequestByGuid ( appSpaceGuid: String, requestGuid: String, completion: @escaping ( _ request: PrivakeyRequest?, _ error: Error? ) -> Void )

Gets a single request based on its identifier.

If the request exists in local cache, the cached item will be returned via completion. At the same time, a call will be made to the CX Server to get the latest data for the request. When this call returns, the data will be sent through PrivakeyCXDelegate.onGetRequestsResult(). See the Delegates page for more info.

If the request does not exist in local cache, the call to the CX Server is made and its data is returned through completion.

Parameters
appSpaceGuidIdentifier of the App Space the request belongs to.
requestGuidThe request identifier of the request that you are fetching the details for.
completionCompletion handler with these params:
request - The matching request.
error - nil if successful, otherwise an error object.

getRequestsByStatus

public func getRequestsByStatus ( appSpaceGuid: String, requestStatus: RequestStatus, completion: @escaping ( _ requests: [PKRequest]?, _ error: Error? ) -> Void )

Get all requests of a certain status for a particular App Space. This method is a shorthand for the other method, getRequests().

Parameters
appSpaceGuidIdentifier of the App Space to get requests for.
requestStatusStatus of requests to fetch.
completionCompletion handler with these params:
requests - The matching requests.
error - nil if successful, otherwise an error object.

getRequests

public func getRequests ( appSpaceGuid: String, requestStatus: RequestStatus?, beginDate: Date?, endDate: Date?, limit: Int?, completion: @escaping ( _ requests: [PKRequest]?, _ error: Error? ) -> Void )

Request search method. This will return all the requests that meet the specified conditions.

Parameters
appSpaceGuidIdentifier of the App Space to get requests for.
requestStatusStatus of requests to fetch.
beginDateThe beginning of the date range. Returns requests that were created after and including this date.
endDateThe end of the date range. Returns requests that were created before and including this date.
limitThe max number of requests to return. If this is less than 1, it will be automatically set to 50.
completionCompletion handler with these params:
requests - The matching requests.
error - nil if successful, otherwise an error object.

processRequest

public func processRequest ( appSpaceGuid: String, requestGuid: String, password: String?, selectedButtonIndex: Int, responseContent: String?, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

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

Parameters
appSpaceGuidIdentifier of the App Space the request belongs to.
requestGuidIdentifier of the Request to process.
passwordThe password used to unlock the Privakey account's Authorization Key, used for approving requests that require strong authentication. Can be null for requests that do not require strong authentication.
selectedButtonIndexThe JSON index of the button object that was selected by the user. This is used to determine the authorization level the request requires to be processed. It can be used to confirm the action the user selected.
responseContentThis field is used to record any data as a result of user interaction that should be signed with the request. EG. user inputted form data, typed text input.
completionCompletion handler with these params:
success - True if successful.
error - nil if successful, otherwise an error object.

processRequestBiometric

public func processRequestBiometric ( appSpaceGuid: String, requestGuid: String, selectedButtonIndex: Int, responseContent: String?, biometricAuthReason: String, completion: @escaping ( _ success: Bool?, _ error: Error? ) -> Void )

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

Parameters
appSpaceGuidIdentifier of the App Space the request belongs to.
requestGuidIdentifier of the Request to process.
selectedButtonIndexThe JSON index of the button object that was selected by the user. This is used to determine the authorization level the request requires to be processed. It can be used to confirm the action the user selected.
responseContentThis field is used to record any data as a result of user interaction that should be signed with the request. EG. user inputed form data, typed text input.
biometricAuthReasonThe Touch/Face ID reason for requesting authentication, which displays in the authentication dialog presented to the user.
completionCompletion handler with these params:
success - True if successful.
error - nil if successful, otherwise an error object.

requestNotificationActedOn

public func requestNotificationActedOn ( notificationUserInfo: [AnyHashable: Any] )

Uploads telemetry data for the event that a request notification is clicked. Call this method from within you App Delegate's notification handler, E.G. inside of:

func userNotificationCenter(_ center: UNUserNotificationCenter, didReceive response: UNNotificationResponse, withCompletionHandler completionHandler: @escaping () -> Void)
Parameters
notificationUserInfoThe received Privakey notification userInfo forwarded from your app delegate's notification handler.

requestViewStart

public func requestViewStart ( request: PrivakeyRequest )

Initiates the process of uploading a request viewed telemetry event. Call this method whenever request content is being displayed in the app. Once the view goes off screen, be sure to call requestViewEnd(request) to complete the process.

Parameters
requestThe Privakey Request being displayed.

requestViewEnd

public func requestViewEnd ( request: PrivakeyRequest )

Completes the process of uploading a request viewed telemetry event. Call this method whenever request content is done being displayed in the app. It should be called as a followup to requestViewStart(request), above.

Parameters
requestThe Privakey Request being displayed.

handlePrivakeyNotification

public func handlePrivakeyNotification ( notificationUserInfo: [AnyHashable : Any], completion: @escaping ( _ didRevokeDevice: Bool ) -> Void )

Processes Privakey notifications. Forward any received Privakey notifications to this method. If a notification to revoke is received, then didRevokeDevice will be true and you should clear your app data accordingly.

Parameters
notificationUserInfoThe received Privakey notification userInfo forwarded from your app delegate's notification handler.
completionCompletion handler with these params:
didRevokeDevice - True if the device was revoked.

checkStatus

public func checkStatus ( completion: @escaping ( _ didRevokeDevice: Bool, _ didSuspendAccount: Bool ) -> Void )

Checks if the current device or associated account status has changed and handles it appropriately. If the device is revoked, then didRevokeDevice will be true and you should clear your app data accordingly. If the account was suspended, then didSuspendAccount will be true and you should update the UI accordingly.

Parameters
completionCompletion handler with these params:
didRevokeDevice - True if the device was revoked.
didSuspendAccount - True if the account was suspended.