Authentication

Authentication outside the browser

The links in the previous page that generate API content in your browser work because you're logged into your account and the server is already happy that you are, in fact, you. When you write scripts or tools to access the API outside of your browser session, you must provide your API key to authenticate on every request.

Taking a leaf out of the book of some other clever folks, the Handshake API requires that you use HTTP basic authentication to pass your API key with each request. You should pass the API key as the username along with 'X' as the password.

For example, you could use the command below to dump the JSON data for your orders. Replace the 2c493d74 with your own API key (which will be much longer):

$ curl -u 2c493d74:X https://app.handshake-app.com/api/v2/orders

Throughout this documentation, we will omit the -u 2c493d74:X argument to curl in the examples for sake of brevity, however when trying these examples out yourself you must provide the authentication on every request.

A note about security

Your API key uniquely identifies you and you should treat it with the same care and secrecy as you do your main account password. If your API key is compromised by an attacker, they will be able to access the data in your account, so if you suspect that this might have happened, you should generate a new one.

In particular, if you accidentally try to access the API using plain HTTP instead of HTTPS, then it is possible that a man-in-the-middle attacker has just intercepted your API key and is now able to use it to access data in your account. If you ever accidentally do this, Handshake will automatically destroy your API key to prevent anyone else from using it to access your account. You can easily generate a new one from your user page.