How to sign requests using (JWS)
When integrating Fayda you will find that you have to sign some of your requests. This means you have to include a parameter in the request header (called Signature) that contains a JSON Web Signature (JWS). We require this to ensure the integrity of the data you’re sending. You can learn more about JWS here.
To demonstrate what a signature should look like let’s make a request to the OTP Request Service (which enables authentication partners to request for an OTP for an individual). The API gateway for this service is
https://{base_url}/idauthentication/v1/otp/:FISP-LicenseKey/:Partner-ID/:Partner-Api-Key
As you’ve seen from the API Specifications the request should contain the following parameters
Resource Details | Description |
|---|---|
Response format | JSON |
Requires Authentication | Yes |
Request Header Parameters
Name | Required | description |
|---|---|---|
Authorization | Y | response from client authentication service |
Signature | Y | signature of the authentication request the whole body in JWS format. |
Request Body Parameters
Name | Required | description |
|---|---|---|
id | Y | API ID- “fayda.identity.otp” |
Version | Y | The API version to be used |
transactionID | Y | Transaction ID of the request. Eg: “1234567890” |
requestTime | Y | Request capture time. Eg: “2021-09/17T11:07:48.086+03:00 |
env | Y | Target Environment. “Staging”, “Developer”, “Pree-Production” “Production” |
domainUri | Y | Unique URI per auth providers (if any). For now it is the Fayda Platform itself. |
idType | Y | ID type of the individual. Values are - VID, UIN. Default is VID. |
otpChannel | Y | Channel to send the OTP. Values are - EMAIL, PHONE |
Let’s focus on the request payload, which is the data we will sign. Here’s what a typical request JSON should look like
{
"id": "fayda.identity.otp",
"requestTime": "2022-08-29T19:25:42.289+05:30",
"env": "Developer",
"version": "1.0",
"domainUri": "https://dev.fayda.et",
"transactionID": "1234512345",
"individualId": "4157164106193802",
"individualIdType": "VID",
"otpChannel": [
"PHONE"
]
}The purpose of signing the data, as stated before, is to ensure its integrity in transit.
Regardless of the programming language, you’re using you should make sure that your signature header specifies that
The algorithm of the signature is RSA256
You’re using JWS
Here’s what the header portion of your signature should look like
{
"x5c": [
"YOUR PUBLIC KEY GOES HERE"
],
"alg": "RS256",
"typ": "JWS"
}
After signing your data and making an API request if you encounter a response similar to
"errorMessage": "Digital signature verification failed"