Web API Overview

The RapID Service provides a RESTful Web API which allows you to request and then manage credentials for your end-users. Operations that you can perform using the API include:

• Request a credential that will be deployed to a device belonging to one of your end-users.
• Request a replacement credential, e.g. for an end-user's new or temporary replacement device.
• Prevent the automatic renewal of a credential by an end-user who no longer subscribes to your service.

In order to support testing, you can also use the API to request special test certificates which allow you to develop and test your service and mobile app without consuming real licenses. In addition to this, we provide CollectRapidCertificate.exe, a command-line tool that allows you to collect real or test credentials that you have previously requested using the RapID Service Web API. See Testing RapID for further information about using this tool.

The RESTful credential management functions are hosted using two way TLS at: https://request.rapidauth.com/rapid. Whenever you make a call to this HTTPS-based Web API, you must provide the service authentication certificate that you downloaded from the RapID Dashboard. This certificate proves your identity to the RapID Service in the same way that the SSL certificate on the RapID Service allows you to be certain that you are connecting with RapID. Together, these two certificates ensure that all your credential management operations use mutual authentication. For more information, see Explaining certificates.

The RESTful Web API includes the following routes:

• Credentials (base URL: https://request.rapidauth.com/rapid/credentials). This is the principle route through which you will request and manage credentials. It is keyed using the anonymous identifiers that you create for each of your end-users' devices.

• Requests (base URL: https://request.rapidauth.com/rapid/requests). This alternative route allows you to manage credentials if you choose not to use unique anonymous identifiers for each end-user device. It is keyed using the RequestIds that the RapID Service generates for you.

Each API's section contains full details of how to use that particular API. In summary, you request a credential for one of your end-users' devices by POSTing to the credentials URL. The credential is then collected from the RapID Service and securely deployed to your end-users' device by the RapID Mobile SDK in your mobile app (see Mobile SDK Overview).

In order to facilitate the automatic renewal of these credentials at the end of their lifetime, the RapID Service maintains information about all the credentials that are deployed. You can use the Web API with specific verbs to update a specific credential (PATCH) and thus prevent its automatic renewal. You can also request a credential replacement - for example because the end-user's device has been lost (POST).

An additional facility in the RapID Service is the Diagnostics route: https://request.rapidauth.com/rapid/diagnostics. This route supports your testing by allowing you to reseed test requests so that the tests can be repeated.

Make anonymous IDs unique per device

We strongly recommend that you use unique anonymous identifiers such that each one identifies a single end-user’s device to which the credential will be deployed. You should also not include any personally identifiable information of your customer in the anonymous identifier. You will manage these credentials exclusively using the https://request.rapidauth.com/rapid/credentials API.
This approach gives you full control over preventing automatic renewal of expired credentials and issuing replacements.

We provide the https://request.rapidauth.com/rapid/requests API as an alternative in case you have a need to use the same anonymous identifier for all devices used by each of your end-users. In this scenario you must store the request IDs that were generated by the RapID Service when initially requesting a credential for each device. This will be the only way to prevent it being renewed or to arrange a replacement.

Internet media type

Where an API endpoint requires data, that data is supplied as a JSON object in the request body. For example, to request a new credential the payload would be of the form:

{
    "AnonId":"<AnonId for User>"
}

Field	Type	Description
AnonId	string	A unique anonymous id generated by you to identify the end user's device

Responses are also JSON objects. For example:

{
    "AnonId":"<AnonId for User>",
    "RequestId":"xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "PreventCollection":false
}

Field	Type	Description
AnonId	string	The unique anonymous id provided by you in the request body
RequestId	string	A unique identifier for this request generated by the RapID Service for this credential
PreventCollection	boolean	Identifies whether it is possible for the credential to be collected by an end user

Error Reporting

All API endpoints report errors using a combination of HTTP Status codes as described here and JSON objects such as the example below:

{
    "Number":"0000",
    "Message":"..."
}

Name	Type	Description
Number	integer	RapID specific error code.
Message	string	Detail about the error that occurred.

Creating a PEM file from a PFX

The examples in the following sections use cURL to send requests to the RapID API. Since the requests use mutual authentication, you must supply your service authentication certificate (SAC) with each request. This is achieved via cURL by using a .pem version of the SAC.

Note: This requires "openssl" to be installed on your system.

To create a .pem file from your SAC use the following in a command prompt:

openssl pkcs12 -in ./SAC.pfx -out SAC.pem -nodes