MIRACLTrust

CLASS

# MIRACLTrust

@objc open class MIRACLTrust: NSObject, Loggable

Main class of the SDK used for all possible actions like registration and authentication.

# Properties

# users

@objc public var users: [User] = []

# projectId

@objc public var projectId: String

# Methods

# getInstance()

@objc public class func getInstance() -> MIRACLTrust

Getting singleton instance of the MIRACLTrust class.

  • Returns: singleton instance of the MIRACLTrust class.

# configure(with:)

@objc public class func configure(with configuration: Configuration) throws

Configure SDK with values issued by MIRACL and stored in the Configuration object. It is recommended to be called right after the application is launched.

  • Parameter configuration:object storing configurations of the SDK.

# Parameters

Name Description
configuration object storing configurations of the SDK.

# setProjectId(projectId:)

@objc public func setProjectId(projectId: String) throws

Configure a new project ID when the SDK have to work with a different project.

  • Parameters:
    • projectId: Project ID setting for the MIRACL Platform that needs to be updated.

# Parameters

Name Description
projectId Project ID setting for the MIRACL Platform that needs to be updated.

# sendVerificationEmail(userId:authenticationSessionDetails:completionHandler:)

@objc public func sendVerificationEmail(
    userId: String,
    authenticationSessionDetails: AuthenticationSessionDetails? = nil,
    completionHandler: @escaping VerificationCompletionHandler
)

Sending email for user id verification.

  • Parameters:
  • userId: identifier of the user identity. To verify identity this identifier needs to be valid email address.
  • authenticationSessionDetails: details for an authentication session.
  • completionHandler: a closure called when the verification has been completed. It can contain a verification response object or an optional error object.

# getActivationToken(verificationURL:completionHandler:)

@objc public func getActivationToken(
    verificationURL: URL,
    completionHandler: @escaping ActivationTokenCompletionHandler
)

The method confirms user verification and as a result, an activation token is obtained. This activation token should be used in the registration process.

  • Parameters:
    • verificationURL: a verification URL received as part of the verification process.
    • completionHandler: a closure called when the verification has been confirmed. It can contain an optional ActivationTokenResponse object and an optional error object.

# Parameters

Name Description
verificationURL a verification URL received as part of the verification process.
completionHandler a closure called when the verification has been confirmed. It can contain an optional ActivationTokenResponse object and an optional error object.

# register(for:activationToken:pushNotificationsToken:didRequestPinHandler:completionHandler:)

@objc public func register(
    for userId: String,
    activationToken: String,
    pushNotificationsToken: String? = nil,
    didRequestPinHandler: @escaping PinRequestHandler,
    completionHandler: @escaping RegistrationCompletionHandler
)

Creates a new identity in the MIRACL platform.

  • Parameters:
    • userId: an identifier of the user (e.g email address).
    • activationToken: a token obtained during the user verification process indicating that the user has been already verified.
    • pushNotificationsToken: current device push notifications token. This is used when push notifications for authentication are enabled in the platform.
    • didRequestPinHandler: a closure called when the PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
    • completionHandler: a closure called when creating a new identity has finished. It can contain an error object or the User where both of them are optional objects.

# Parameters

Name Description
userId an identifier of the user (e.g email address).
activationToken a token obtained during the user verification process indicating that the user has been already verified.
pushNotificationsToken current device push notifications token. This is used when push notifications for authentication are enabled in the platform.
didRequestPinHandler a closure called when the PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
completionHandler a closure called when creating a new identity has finished. It can contain an error object or the User where both of them are optional objects.

# authenticate(user:didRequestPinHandler:completionHandler:)

public func authenticate(
    user: User,
    didRequestPinHandler: @escaping PinRequestHandler,
    completionHandler: @escaping JWTCompletionHandler
)

Authenticate identity to the MIRACL Trust platform by generating a JWT authentication token.

Use this method to authenticate within your application.

After the JWT authentication token is generated, it needs to be sent to the application server for verification. When received, the application server should verify the token signature using the MIRACL Trust JWKS endpoint and the audience claim which in this case is the application project ID.

  • Parameters:
    • user: object that keeps an authentication identity in it.
    • didRequestPinHandler: a closure called when the PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
    • completionHandler: a closure called when the JWT is generated. It can contain an optional JWT token or an optional error object.

# Parameters

Name Description
user object that keeps an authentication identity in it.
didRequestPinHandler a closure called when the PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
completionHandler a closure called when the JWT is generated. It can contain an optional JWT token or an optional error object.

# authenticateWithQRCode(user:qrCode:didRequestPinHandler:completionHandler:)

public func authenticateWithQRCode(
    user: User,
    qrCode: String,
    didRequestPinHandler: @escaping PinRequestHandler,
    completionHandler: @escaping AuthenticationCompletionHandler
)

Authenticates identity in the MIRACL platform.

Use this method to authenticate another device or application with the usage of QR Code presented on MIRACL login page.

  • Parameters:
    • user: object that keeps an authentication identity in it.
    • qrCode: a string read from the QR code.
    • didRequestPinHandler: a closure called when the PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
    • completionHandler: a closure called when the identity is authenticated. It can contain a boolean flag representing the result of the authentication or an optional error object.

# Parameters

Name Description
user object that keeps an authentication identity in it.
qrCode a string read from the QR code.
didRequestPinHandler a closure called when the PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
completionHandler a closure called when the identity is authenticated. It can contain a boolean flag representing the result of the authentication or an optional error object.

# authenticateWithPushNotificationPayload(payload:didRequestPinHandler:completionHandler:)

public func authenticateWithPushNotificationPayload(
    payload: [AnyHashable: Any],
    didRequestPinHandler: @escaping PinRequestHandler,
    completionHandler: @escaping AuthenticationCompletionHandler
)

Authenticates identity in the MIRACL platform.

Use this method when you want to authenticate another device or application with the usage of Push notifications sent by a MIRACL platform.

  • Parameters:
    • payload: payload dictionary received from push notification.
    • didRequestPinHandler: a closure called when the PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
    • completionHandler: a closure called when the identity is authenticated. It can contain a boolean flag representing the result of the authentication or an optional error object.

# Parameters

Name Description
payload payload dictionary received from push notification.
didRequestPinHandler a closure called when the PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
completionHandler a closure called when the identity is authenticated. It can contain a boolean flag representing the result of the authentication or an optional error object.

# authenticateWithUniversalLinkURL(user:universalLinkURL:didRequestPinHandler:completionHandler:)

public func authenticateWithUniversalLinkURL(
    user: User,
    universalLinkURL: URL,
    didRequestPinHandler: @escaping PinRequestHandler,
    completionHandler: @escaping AuthenticationCompletionHandler
)

Authenticates identity in the MIRACL platform.

Use this method to authenticate another device or application with the usage of Universal Link created by a MIRACL platform.

  • Parameters:
    • user: object that keeps an authentication identity in it.
    • universalLinkURL: universal link for authentication.
    • didRequestPinHandler: a closure called when the PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
    • completionHandler: a closure called when the identity is authenticated. It can contain a boolean flag representing the result of the authentication or an optional error object.

# Parameters

Name Description
user object that keeps an authentication identity in it.
universalLinkURL universal link for authentication.
didRequestPinHandler a closure called when the PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
completionHandler a closure called when the identity is authenticated. It can contain a boolean flag representing the result of the authentication or an optional error object.

# generateOTP(user:didRequestPinHandler:completionHandler:)

@objc public func generateOTP(
    user: User,
    didRequestPinHandler: @escaping PinRequestHandler,
    completionHandler: @escaping OTPCompletionHandler
)

Generate OTP against the MIRACL platform.

  • Parameters:
    • user: an already registered user with authentication identity.
    • didRequestPinHandler: a closure called when the PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
    • completionHandler: a closure called when the OTP has been generated. It can contain a generated OTP object or an optional error object.

# Parameters

Name Description
user an already registered user with authentication identity.
didRequestPinHandler a closure called when the PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
completionHandler a closure called when the OTP has been generated. It can contain a generated OTP object or an optional error object.

# generateQuickCode(user:didRequestPinHandler:completionHandler:)

@objc public func generateQuickCode(
    user: User,
    didRequestPinHandler: @escaping PinRequestHandler,
    completionHandler: @escaping QuickCodeCompletionHandler
)

Generate QuickCode against the MIRACL platform.

  • Parameters:
    • user: an already registered user with authentication identity.
    • didRequestPinHandler: a closure called when the PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
    • completionHandler: a closure called when the QuickCode has been generated. It can contain a generated OTP object or an optional error object.

# Parameters

Name Description
user an already registered user with authentication identity.
didRequestPinHandler a closure called when the PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
completionHandler a closure called when the QuickCode has been generated. It can contain a generated OTP object or an optional error object.

# getAuthenticationSessionDetailsFromQRCode(qrCode:completionHandler:)

public func getAuthenticationSessionDetailsFromQRCode(
    qrCode: String,
    completionHandler: @escaping AuthenticationSessionDetailsCompletionHandler
)

Get authentication session details from MIRACL’s platform based on session identifier.

Use this method to get session details for application that tries to authenticate against MIRACL Platform with the help of QR Code.

  • Parameters:
    • qrCode: a string read from the QR code.
    • completionHandler: a closure called when the authentication session details are fetched.It can contain a newly fetched authentication session details optional object and an optional error object.

# Parameters

Name Description
qrCode a string read from the QR code.
completionHandler a closure called when the authentication session details are fetched.It can contain a newly fetched authentication session details optional object and an optional error object.

# getAuthenticationSessionDetailsFromUniversalLinkURL(universalLinkURL:completionHandler:)

public func getAuthenticationSessionDetailsFromUniversalLinkURL(
    universalLinkURL: URL,
    completionHandler: @escaping AuthenticationSessionDetailsCompletionHandler
)

Get authentication session details from MIRACL’s platform based on session identifier.

Use this method to get authentication session details for application that tries to authenticate against MIRACL Platform with the help of Universal Link URL.

  • Parameters:
    • universalLinkURL: universal link for authentication.
    • completionHandler: a closure called when the authentication session details are fetched.It can contain a newly fetched authentication session details optional object and an optional error object.

# Parameters

Name Description
universalLinkURL universal link for authentication.
completionHandler a closure called when the authentication session details are fetched.It can contain a newly fetched authentication session details optional object and an optional error object.

# getAuthenticationSessionDetailsFromPushNotificationPayload(pushNotificationPayload:completionHandler:)

public func getAuthenticationSessionDetailsFromPushNotificationPayload(
    pushNotificationPayload: [AnyHashable: Any],
    completionHandler: @escaping AuthenticationSessionDetailsCompletionHandler
)

Get authentication session details from MIRACL’s platform based on session identifier.

Use this method to get authentication session details for application that tries to authenticate against MIRACL Platform with the help of push notifications payload

  • Parameters:
    • pushNotificationPayload: payload dictionary received from push notification.
    • completionHandler: a closure called when the authentication session details are fetched.It can contain a newly fetched authentication session details optional object and an optional error object.

# Parameters

Name Description
pushNotificationPayload payload dictionary received from push notification.
completionHandler a closure called when the authentication session details are fetched.It can contain a newly fetched authentication session details optional object and an optional error object.

# abortAuthenticationSession(authenticationSessionDetails:completionHandler:)

public func abortAuthenticationSession(
    authenticationSessionDetails: AuthenticationSessionDetails,
    completionHandler: @escaping AuthenticationSessionAborterCompletionHandler
)

Cancel the authentication session by its SessionDetails object

  • Parameters:
    • authenticationSessionDetails: details for authentication session, that is in progress.
    • completionHandler: a closure called when the authentication session is aborted. It can contain a boolean flag representing the result of the abortion and an optional error object.

# Parameters

Name Description
authenticationSessionDetails details for authentication session, that is in progress.
completionHandler a closure called when the authentication session is aborted. It can contain a boolean flag representing the result of the abortion and an optional error object.

# getSigningSessionDetailsFromQRCode(qrCode:completionHandler:)

public func getSigningSessionDetailsFromQRCode(
    qrCode: String,
    completionHandler: @escaping SigningSessionDetailsCompletionHandler
)

Get signing session details from MIRACL’s platform based on session identifier.

Use this method to get signing session details for application that tries to sign against MIRACL Platform with the usage of QR Code.

  • Parameters:
    • qrCode: a string read from the QR code.
    • completionHandler: a closure called when the session details are fetched.It can contain a newly fetched signing session details optional object and an optional error object.

# Parameters

Name Description
qrCode a string read from the QR code.
completionHandler a closure called when the session details are fetched.It can contain a newly fetched signing session details optional object and an optional error object.

# getSigningSessionDetailsFromUniversalLinkURL(universalLinkURL:completionHandler:)

public func getSigningSessionDetailsFromUniversalLinkURL(
    universalLinkURL: URL,
    completionHandler: @escaping SigningSessionDetailsCompletionHandler
)

Get signing session details from MIRACL’s platform based on session identifier.

Use this method to get signing session details for application that tries to sign against MIRACL Platform with the usage of Universal Link URL.

  • Parameters:
    • universalLinkURL: universal link for signing.
    • completionHandler: a closure called when the session details are fetched.It can contain a newly fetched signing session details optional object and an optional error object.

# Parameters

Name Description
universalLinkURL universal link for signing.
completionHandler a closure called when the session details are fetched.It can contain a newly fetched signing session details optional object and an optional error object.

# abortSigningSession(signingSessionDetails:completionHandler:)

public func abortSigningSession(
    signingSessionDetails: SigningSessionDetails,
    completionHandler: @escaping SigningSessionAborterCompletionHandler
)

Cancel the signing session by its SigningSessionDetails object

  • Parameters:
    • signingSessionDetails: details for signing session, that is in progress.
    • completionHandler: a closure called when the signing session is aborted. It can contain a boolean flag representing the result of the abortion and an optional error object.

# Parameters

Name Description
signingSessionDetails details for signing session, that is in progress.
completionHandler a closure called when the signing session is aborted. It can contain a boolean flag representing the result of the abortion and an optional error object.

# sign(message:timestamp:user:signingSessionDetails:didRequestSigningPinHandler:completionHandler:)

@objc public func sign(
    message: Data,
    timestamp: Date,
    user: User,
    signingSessionDetails: SigningSessionDetails? = nil,
    didRequestSigningPinHandler: @escaping PinRequestHandler,
    completionHandler: @escaping SigningCompletionHandler
)

Create a cryptographic signature of a given document.

  • Parameters:
    • message: the hash of a given document.
    • timestamp: when the document has been signed.
    • user: an already registered user with signing identity.
    • didRequestSigningPinHandler: a closure called when the signing identity PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
    • signingSessionDetails: details for signing session, that is in progress.
    • completionHandler: a closure called when the signing has completed. It can contain a newly created Signature object and an optional error object.

# Parameters

Name Description
message the hash of a given document.
timestamp when the document has been signed.
user an already registered user with signing identity.
didRequestSigningPinHandler a closure called when the signing identity PIN code is needed from the SDK. It can be used to show UI for entering the PIN code. Its parameter is another closure that is mandatory to be called after the user finishes their action.
signingSessionDetails details for signing session, that is in progress.
completionHandler a closure called when the signing has completed. It can contain a newly created Signature object and an optional error object.

# getUser(by:projectId:)

@objc public func getUser(by userId: String, projectId: String? = nil) -> User?

Getting user by its project Id and its userId.

  • Parameters:
    • userId: id of the user. Can be email or any other string.
    • projectId: project id taken from the portal.
  • Returns: User object from the database. Returns nil if there is no such object in the storage.

# Parameters

Name Description
userId id of the user. Can be email or any other string.
projectId project id taken from the portal.

# delete(user:)

@objc public func delete(user: User) throws

Deletes a user from user storage with its signing and authentication identities.

  • Parameter user: object that needs to be deleted.

# Parameters

Name Description
user object that needs to be deleted.