HTTP Message signatures

The Investment API requires that all HTTP requests contain cryptographic signatures. This signature proves that you are the one making the request and that the payload of the request has not been tampered with.

Request are signed using the key-pair generated in the Getting Started Tutorial.

WEBHOOKS

We also sign the requests we make to your webhook endpoints. Validation of webhook requests is discussed separately in Validating Webhook Signatures


This tutorial will walk you through the process signing an HTTP message. The intent is that you can take this knowledge and implement this process within your application.

UPGRADING

If you have an existing integration with the Upvest Investment API and would like to upgrade your HTTP Message signature version, please read the Upgrade Tutorial instead of this one.


Prerequisites

Please make sure you meet the following conditions before attempting this tutorial.

 ✓   Complete "Getting Started"
Details

Before you'll be able to make successful requests against the Investment API, using HTTP signatures, you'll need to have set up cryptographic keys and have received API credentials. The "Getting Started Tutorial" will lead you through the processes involved.


 ✓   Experience with HTTP and Cryptography
Details

Although the HTTP Message signing standards are not complex, you will need to know how to construct HTTP messages and create cryptographic signatures.

You will also need to apply the knowledge we provide here to the programming language, libraries and frameworks you choose to implement your product in.



Let's get started!

   Preparation

Before following one of our walk-throughs of the HTTP Message Signing protocols, we suggest you first complete the following preparatory steps.

1.1   Choose HTTP Message Signature Versions

You'll need to understand which HTTP Message Signature versions to implement for API calls and Webhook handlers.

The currently recommended choices are:

  • Version 15 for signing your requests.
  • Version 6 for validation of webhooks.

If you accept those choices you can move on. If you'd like to research more before making a choice, please read the sub-task document.

1.2   Sample implementation

In step 2, below we'll walk you through the process signing an HTTP Message.

However, it's often easier to understand an existing implementation than trying to think through the implications of a description. For that purpose, we provide some simple examples that you can use as a reference. If you'd like to take a look at them, please read the sub-task.

Additionally, if you're going to use Python to call the Investment API, you'll also find our off-the-shelf Python library for HTTP Message Signatures linked in this sub-task.

You should now clearly understand what HTTP Message Signature versions you need to implement, and have access to a fully working example implementation in Python.

From here, we can move onto the walk-throughs.

   Implementation Choice

Based on what you learned about the supported version of the HTTP Message Signature protocol, choos the correct section below. These tutorials will walk you through the message signing process using that version of the protocol.

Option A   Implementing HTTP Message Signatures v6

In this sub-task we'll explain how to implement v6 of the HTTP Message Signatures recommendation.

Option B   Implementing HTTP Message Signatures v15

In this sub-task we'll explain how to implement v15 of the HTTP Message Signatures recommendation.

   Ready to implement!

Congratulations, you've completed the "Implementing HTTP Message Signatures" tutorial!

By utilizing the provided implementation guides and sample implementations, we hope that you were able to make calls to the Upvest Investment API from your application.

DEVX SUPPORT

Security measures can make debugging HTTP Message signatures `difficult. If you are having difficulty with this task, please reach out to Upvest's Developer eXperience team, via your normal support channels. We will be happy to assist you.


Next steps

We suggest that you now proceed by:

We wish you joy in your work with the Upvest Investment API!