APIs & You, with JWTs and Cookies

Let’s connect to the Pareto Sentinel API! This is the API for Pareto Network authentication, scoring, and content. Our website hosts the reference implementation and you can connect to it so that you can build your own apps and functionality.

The API documentation lives here https://www.pareto.network/api-docs/

and this is an open source document which means you can contribute to it here https://github.com/ParetoNetwork/ParetoSentinelAPI

Introduction

The Pareto Network uses JSON Web Tokens (JWT, pronounced “jot” if you have to) which are generated by signing your Ethereum address.

Programmatically authenticating with JWT can be counterintuitive, so this walkthrough is how to get your JWT and never have to worry about it again!

The goal of this tutorial is to show you how to get your JWT which is a cookie, and how to set it in your REST client to make authenticated API calls.

This tutorial assumes you are familiar with everything said so far, or are not intimidated to find out on your own.

For the best experience, you need:

Google Chrome

Metamask browser extension

(Optional) a tiny bit of PARETO in your Metamask account

Postman, or any REST client

Follow Along

As established, the JWT is a cookie. API requests to authenticated endpoints in this system simply check for the existence of a valid cookie and grant you access. Initially getting your JWT This requires you to have Metamask installed. On www.pareto.network click the Access button and Metamask pops open with a request to sign a message. Click sign.

Signing a message to sign in to the Pareto Network

2. Upon successful sign in, you will be in to the Intel dashboard, where other content contributors are disclosing intel. Right click to see your browser’s menu, and click ‘inspect’ to bring up Chrome Inspector.

3. Chrome inspector is a powerful tool for analyzing websites. Now that Chrome inspector is open, find the “Network” tab and then refresh the web page.

The network tab shows all the communication requests that the website attempts to make, and details about each request. Since it shows it live, refreshing the page makes all the requests happen again and they will get recorded this time.

4. Websites make a lot of requets so we can filter them to RESTful requests by clicking the XHR button.

5. In the following screenshot, we show that there are just a few RESTful and XHR requests remaining, and they are listed in the left panel called ‘Name’.

Some users may need to reshuffle the visible Chrome Inspector panels.

Click the ‘auth’ entry, this is a request that checks to see if you are properly signed in. When ‘auth’ fails, you cannot access the intel feed or other authenticated endpoints, so how does it know?

6. After clicking the ‘auth’ request, more metadata about it becomes visible. Find the headers tab, and scroll down to the section called ‘Request Headers’. There should be a lot of information. What you want is the “Cookie” key.

7. Find Cookie and notice the key:value pair named pareto_auth. These are the cookies you have been looking for 🍪 You will want to copy everything from pareto_auth=

ex. pareto_auth=58hsvndsjkfalj9348j39f888mq9cdsjkncpqwnkj81kadk

This is your JWT. Although you can read and copy the cookie, we use secure readonly cookies which is partially why this is so complicated.

Now with this information you can programmatically make API calls to the protected routes.

Lets try this on the endpoint https://api.pareto.network/v1/intel using Postman, which is a great REST client for local development. Second best to curl

Welcome to POSTMAN

Trying an API request for the first time

8. In the address field, you can put in the url and total path of the route, make sure the request type is set to GET, and press SEND

You should very quickly get a response of 401 UNAUTHORIZED. And this is because you haven’t set the cookie yet! Your browser has the cookie, but now your REST client needs the cookie too.

Postman’s visual interface may change in the future, but you can set the cookie in the Cookies section right underneath the ‘Send’ button.

Cookies section 🍪

9. Set the cookie by first typing in the domain name that the cookie is relevant for.

“pareto.network”

then click Add and this creates a pareto.network entry at the bottom of your cookie list. Scroll down if you can’t see it, since you program all the time and have a ton of cookies like me.

10. Click the pareto.network entry and you should already have an entry called Cookie_1 made and partially prefilled for you. The “Cookie_1” name will automatically be replaced with “pareto_auth” when we are done

11. paste in your JWT. pareto_auth=290429340234qsdkaskdjfaie or whatever you were given should now replace Cookie_1=value . The semicolon should still be there after it. You are replacing one key=value pair with another, and then click save.

Make sure the additional cookie data related to path and domain are still present and separated by a space and a semicolon.

12. Now when you click send, the server will authorize you and send you data in return. Viola! With this you can create telegram bots, slack apps, and monitor how other user’s scores change over time, and things none of us have thought of yet!

This request will be optimized soon :) but if you don’t know why it isn’t, don’t worry about it

And now build the rest of the app. Cheers!

Highly inspirational

If you have any issues with the API or the documentation, come visit the github here https://github.com/ParetoNetwork/ParetoSentinelAPI to notify us of an issue or submit a fix on your own!

We also encourage discussion about the API on our Telegram: https://t.me/paretonetworkdiscussion

Thank you for your time!

Eric Lamison-White