RapID Multiple Credential Support

The RapID client library supports multiple credentials on the same device using a label to uniquely identify each credential. This means you can register a credential against a label of your choice and use that credential later by providing the label to identify it. The following methods support multiple credentials:

  • identityExists
  • collectIdentity
  • removeIdentity
  • signData - with label

The following methods, which support only a single credential per device, are now deprecated and should not be used by developers:

  • signData
  • registerDevice

The following methods are still current but they operate on all labels.

  • unregisterDevice
  • isDeviceRegistered

The method unregisterDevice will unregister All labels that you have created in your mobile app and isDeviceRegistered will return true if any label has been registered.

SDK Methods

All methods available on the RapID SDK are outlined below with information pertaining to their use. For specific code samples see the corresponding section on the SDK platform relevant to you.

Entering Background

The RapID client library must be notified when the application enters the background. This is achieved by calling the enteringBackground method. The result of this call will determine if a user will need to re-authenticate their PIN or Fingerprint when resuming the app and performing an action that requires access to the stored credential

Identity Exists

The method identityExists checks whether your app has an existing RapID credential present against a particular label name. It returns a Boolean value of true if a credential is found under the specified label, otherwise false. The result of this call should determine whether you need to perform a new credential request operation for a particular label.

Collect Identity

The method collectIdentity performs all of the internal operations and RapID server communication to create and store a RapID credential against a user defined label name. It replaces the registerDevice method which only supported a single credential per device. You will need to pass in the RequestId that was returned from your server's call to request a new credential and the label you wish to refer to it by. Internally, the RapID client library then examines the device to discover what credential stores are available, selects the most suitable and generated a cryptographic key pair in the store. This is then used to sign a PKCS#10 certificate request, which also binds the RequestId within the signed data.

The certificate request is transmitted to the RapID service, which locates and validates the request. It substitutes the actual unique user id for the request, then creates and returns the certificate to the client.

Finally, the library stores the certificate against the label reference, which is now ready for use. During its interaction with your client keystore, the RapID client library will present any necessary user interface elements to perform user validation such as PIN or finger print enrolment. A RapidStatus value is returned from the operation indicating the result.

Remove Identity

The method removeIdentity is similar to unregisterDevice with the addition of a label name parameter. It will delete only the RapID credential identified by the given label name. All other credentials relating to other label names will remain intact.

Send Request

The sendRequest method performs a two-way TLS operation. The HttpRequest object allows you to specify the HTTP verb, URL, header, body, timeout, label name and authentication mode on a per request basis. It returns a HTTP response object containing response header, body, status and error information. Each platform wraps this core library method in different ways, meaning that in some cases you need to call it explicitly, whereas in other environments it automatically intercepts your HTTP traffic, depending on your configured whitelist of URLs. The server certificate verification carried out by the RapID client library will currently accept expired, revoked or incomplete chained certificates. Intermediary certificates added by a proxy are not supported.

Note: When the sendRequest API method is used for two-way TLS, a change of label to the same URL will cause ALL current sessions to be reset allowing the new credential to be used.

Sign Data

The method signData lets your app sign data with the private key of the RapID credential identified by the given label. It can force the user to re-authenticate depending on the RapidAuthentication parameter passed in. It will return a SignResult object when successful (see platform specific SDKs for more information). This feature's purpose is to implement security features beyond basic TLS client authentication such as transaction signing of out-of-band authentication.

Sign Result

The native RapID client libraries uses the SignResult object as a return type from the signData method. It allows more than one value to be returned from the method. See the relevant platform specific SDKs for more information.

Unregister Device

The method unregisterDevice is intended primarily for app developers as a convenient means of clearing down a RapID app. It will delete All RapID keys and certificates that have been installed, effectively resetting the credential store to its original state.

Is Device Registered

The method isDeviceRegistered checks whether your app has an existing RapID credential present against any label. It returns a Boolean value of true if a credential is present, otherwise false. This method has now been replaced by IdentyExists which checks against a specific label as opposed to checking for any credential.

Verify Data

The method verifyData lets you verify the signed data using the public key from your RapID certificate that has the Digital Signature key usage. The input data is required to be a PKCS7 bundle which contains the original data as well as the signature.


The method logout is intended to ensure that any further secure access requires the user to authenticate again.

Set Dialog Properties

The method setDialogProperties allows the RapID client library PIN create, verify, PIN authentication, fingerprint authentication and message dialog appearance to be customised. Examples are given in the platform specific documentation and the SDK Programmers Guide.

RapID Status Codes

The following RapidStatus error codes are defined for the RapID client library.

Rapid Status Name Value Description
RapidSuccess 0 The request completed successfully
RapidErrorUnknown 1 The client incurred an unknown error
RapidErrorParsingCertificate 2 The client was unable to read the certificate
RapidErrorCertificateJsonNotAString 3 The certificate was not in the format expected by the client
RapidErrorPkcs7IsEmpty 4 The client could not find the certificate from the server
RapidServerErrorUnknown 5 The server incurred an unknown error
RapidServerNoClientCertificateSupplied 6 The server was not supplied with the client certificate
RapidServerNoClientCertificateFound 7 The server was unable to locate the client certificate
RapidServerUnknownClientCertificate 8 The server received an unknown client certificate
RapidServerJWTValidationError 9 The server was unable to validate the JSON Web Token
RapidServerUnableToProcessJWT 10 The server was unable to process the JSON Web Token
RapidServerClientCertificateMismatch 11 The server detected a mismatch with the client certificate
RapidServerJWTThumbprintNotFound 12 The server could not locate the JSON Web Token thumbprint
RapidServerCertificateRequestInvalid 13 The server received an invalid certificate request
RapidServerCertificateRequestTimeout 14 The server received an expired certificate request
RapidServerCertificateRequestFailed 15 The server reported that the certificate request has failed
RapidServerCertificateAlreadyCollected 16 The certificate has already been collected
RapidServerCustomerNotFound 17 The server was unable to find the customer
RapidServerNoCustomerlicenses 18 The server reported that there are no customer licenses
RapidServerCertificateCollectRequestInvalid 19 The server received an invalid collect request from the client
RapidServerRequestNotFound 20 The server reported an unrecognized request
RapidServerCertificateAuthorityNotFound 21 The server was unable to locate the Certificate Authority
RapidServerIdentifierInvalid 22 The server received an invalid identifier
RapidClientAuthCertValidInFuture 23 The client authentication certificate is valid in the future
RapidClientAuthCertExpired 24 The client authentication certificate has expired
RapidClientUserCancelled 25 The client user cancelled an operation
RapidClientUserAuthFailed 26 The client user failed to authenticate. Seen on iOS after three failed Touch ID attempts
RapidClientDeviceBlocked 27 The client device has become PIN/Fingerprint blocked
RapidClientPinNotSet 28 The user’s PIN has not been set on the client
RapidClientCertificateNotValidForSigning 29 The certificate is not valid for signing on the client
RapidClientCertificateNotFound 30 The certificate was not found on the client
RapidClientInvalidParameter 31 An invalid parameter was detected on the client