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 | |
---|---|
apiService | The service to connect to the CX API. Default is PrivakeyCXAPIService(). |
dataService | The data service for Privakey to persist data. Default is CoreDataStack(). |
localAuthenticationService | The Authentication Manager for handling biometrics. Default is LocalAuthenticationManager(). |
pinEntriesService | The 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 | |
---|---|
password | The PIN/Password used to secure the private key for making strong authorizations. |
notificationId | The device notification Id. The ID that is used for the device to receive remote push notifications. |
notificationFramework | The 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. |
deviceName | Friendly human readable device identifier or nickname. |
appSpaceGuid | Identifier of the App Space being bound to this device. |
sessionToken | A 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. |
completion | Completion 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 | |
---|---|
password | The PIN/Password used to secure the private key for making strong authorizations. |
appSpaceGuid | GUID of the new App Space being added |
sessionToken | A 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. |
completion | Completion 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 | |
---|---|
appSpaceGuid | GUID of the new App Space being added |
sessionToken | A 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. |
bioPromptText | Text 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." |
completion | Completion 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 | |
---|---|
completion | Completion 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 | |
---|---|
completion | Completion 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 | |
---|---|
password | The PIN/Password used to secure the private key for making strong authorizations. |
bioPromptText | Text 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." |
completion | Completion 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 | |
---|---|
completion | Completion 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 | |
---|---|
completion | Completion 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 | |
---|---|
oldPassword | The current password used to process strong authorization requests. |
newPassword | The password to replace the oldPassword . |
completion | Completion 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 | |
---|---|
password | The password to validate. |
Returns | |
---|---|
Bool | True 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 | |
---|---|
completion | Completion 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.
appSpaceGuid | Identifier of the App Space credentials to remove. |
completion | Completion 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 | |
---|---|
status | The status of devices that are to be returned. |
completion | Completion 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 | |
---|---|
completion | Completion 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 | |
---|---|
deviceGuid | The device identifier of the device whose data is being requested. |
completion | Completion 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 theNotificationId
on the CX server. The notificationId must always be current to continue receiving push notifications from the CX Server.
Parameters | |
---|---|
name | Friendly human readable device identifier. |
notificationFramework | The 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. |
notificationId | The device notification Id. The ID that is used for the device to receive push notifications. |
completion | Completion 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 | |
---|---|
appSpaceGuid | Identifier of the App Space the request belongs to. |
requestGuid | The request identifier of the request that you are fetching the details for. |
completion | Completion 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 | |
---|---|
appSpaceGuid | Identifier of the App Space to get requests for. |
requestStatus | Status of requests to fetch. |
completion | Completion 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 | |
---|---|
appSpaceGuid | Identifier of the App Space to get requests for. |
requestStatus | Status of requests to fetch. |
beginDate | The beginning of the date range. Returns requests that were created after and including this date. |
endDate | The end of the date range. Returns requests that were created before and including this date. |
limit | The max number of requests to return. If this is less than 1, it will be automatically set to 50. |
completion | Completion 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 | |
---|---|
appSpaceGuid | Identifier of the App Space the request belongs to. |
requestGuid | Identifier of the Request to process. |
password | The 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. |
selectedButtonIndex | The 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. |
responseContent | This 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. |
completion | Completion 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 | |
---|---|
appSpaceGuid | Identifier of the App Space the request belongs to. |
requestGuid | Identifier of the Request to process. |
selectedButtonIndex | The 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. |
responseContent | This 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. |
biometricAuthReason | The Touch/Face ID reason for requesting authentication, which displays in the authentication dialog presented to the user. |
completion | Completion 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 | |
---|---|
notificationUserInfo | The 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 | |
---|---|
request | The 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 | |
---|---|
request | The 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 | |
---|---|
notificationUserInfo | The received Privakey notification userInfo forwarded from your app delegate's notification handler. |
completion | Completion 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 | |
---|---|
completion | Completion handler with these params: didRevokeDevice - True if the device was revoked. didSuspendAccount - True if the account was suspended. |
Updated about 3 years ago