Skip to content

How-To

We have compiled some how-tos, hope these would be helpful when building your product.

Generate key and Sign the APIs

Generate keys

The ReBIT API specification requires API calls to be signed. For this purpose, JSON Web Signature (JWS) is used.

All API request/responses will have to include a header called x-jws-signature with the 'detached content' JWS signature value.

The receiver of the request/response verifies the JWS against the https request/response data.

However, since the JWS signatures do not include the certificates to verify the signature, there is a need to distribute the public keys with the ecosystem partners so that they can verify signatures. The ecosystem partners can thus verify the signature using the public key.

Sharing of Public Key

If you are building your FIU or FIP modules, public key needs to be shared with the ecosystem partners, FIU/FIP to share with AA and vice versa. In the future this will be centralized so communication with ecosystem partners would be seamless for key retrieval, updates, etc.

Saving the Public and Private Key Pair

In order to sign the APIs the Public and Private Key pair is used for signing of the APIs. The Public Key portion will be shared with the AA for verifying the signature. See below section on how to Sign the API request/response

Follow below steps to generate a public key to be shared with AA

  1. Go to the mkjws site

  2. Use the RSA tab which is default option

  3. Enter the following fields

    a. Key Size: 2048 (the default)

    b. Key Use: Select Signature in the dropdown

    c. Algorithm: Select dropdown option corresponding to RS256... using SHA-256

    d. Key ID: Goto to Online UUID Generator and select the version 4 UUID which is generated by default when the page loads. 

    Paste that UUID into the Key ID field

  4. Finally, click on Generate.

  5. Copy the contents of the Public Key text area that is to be shared with ecosystem partner to verify the signature.

Sign the API request/response

All API request/responses will have to include a header called x-jws-signature with the 'detached content' JWS signature value. The receiver of the request/response verifies the JWS against the https request/response data.

More details on the signature security can be found at our github with sample programs on how to generate and verify detached signature

Signature Security Github

Generate a UUID

A UUID is being used for several fields in the API requests, if you wish to generate one during testing see the Online UUI Generator