Request Signatures

When HTTP requests are sent to the IRB Exchange, the request must contain a signature so the IRB Exchange can determine the identity of the sender. Requests are signed with an organization's ID and its private key. Some requests do not need to be signed, such as the ping operation, which is used to test connectivity to the IRB Exchange.

Signing is only necessary for HTTP requests that you manually create. If the IRB Exchange SDK is used to make requests, it will automatically sign the request with the appropriate organization ID and private key that is specified when configured.

When Do You Need to Sign Requests?

When custom code is written to send HTTP requests to the IRB Exchange, code will need to be included to sign the requests. This may be done for the following reasons:

  • There is no IRB Exchange SDK for the programming language being used
  • Complete control over how the request is sent to the IRB Exchange API is needed

Why Are Request Signatures Needed?

The signing process helps secure requests in the following ways.

Identity Verification

Signing makes sure that the request has been sent by a system with a valid organization ID and private key.

Protect Data in Transit

To prevent tampering with a request while it is in transit, some of the key request elements are used to calculate a hash of the request. The resulting hash value is included as part of the request. When the IRB Exchange API receives the request, it uses the same information to calculate a hash and matches it against the hash value included in the request. If the values do not match, the request is rejected.

Protect Against Replay Attacks

A request must reach the IRB Exchange API within three minutes of the time stamp in the request. Otherwise, the IRB Exchange API will deny the request.

Signing Requests

To sign a request, a hash of the request must be calculated. The hash is then encrypted using the private key of the organization sending the request. This is the signature.

The signature is then added to the request using the HTTP Authorization header.

Signing Process

  1. Create a canonical request
  2. Use a private key to encrypt the hash to create a signature
  3. Add the resulting signature to the HTTP request in a header

When the IRB Exchange API receives the request, it performs the same steps to calculate the string to sign. The IRB Exchange then uses the public key of the organization making the request to verify the signature was created using its corresponding private key. If the signature matches, the request is processed. If the signatures don't match, the request is denied.

Find out more about signing requests.