API authentication

Authentication

The Pay on Rails API uses API keys to authenticate requests. If you do not include your key when making an API request, or use one that is incorrect or outdated, Pay on Rails returns an error.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Obtaining your API keys

Preconditions: You must have enabled the Two Factor Authentication (2FA) on https://api-stage.letsbit.io/logged/security

Example using httpie:

  1. Login into your account.
http --session _letsbit_session
https://api-stage.letsbit.io/api/v1/auth/identity/sessions \
email=your@email.com password=changeme otp_code=869663
#otp_code is the 2fa code
  1. Create your API key

This API key is generated only once and can be used forever.

http --session _letsbit_session
https://api-stage.letsbit.io/api/v1/auth/resource/api_keys \
algorithm=HS256 totp_code=869663

Expected response:

{
"kid": "07ffb1bb3230bdb2",
"algorithm": "HS256",
"scope": [],
"state": "active",
"secret": "b914ce270c70b24836d69ffe107c12db",
"created_at": "2021-11-16T19:25:27Z",
"updated_at": "2021-11-16T19:25:27Z"
}
  1. Securely save your API Key and Secret.

How to use API key?

On pay on Rails requests is necessary to include the next 3 headers

X-Auth-Apikey → API key (from previous step).

X-Auth-Nonce → A nonce is an arbitrary number that can be used just once. In our environment you MUST use a millisecond timestamp in UTC time.

#Example
date +%s%3N
1584087661035

Read more about it here

X-Auth-Signature → HMAC-SHA256 signature
calculated using concatenation of X-Auth-Apikey and X-Auth-Nonce

Example of generating X-Auth-Signature:

#python 3
import hmac
import hashlib
nonce = 1
SECRET = 'thekey'
api_key = 'theApikey'
message = '{} {} {}'.format(nonce, api_key)
signature = hmac.new(bytes(SECRET , 'latin-1'), msg = bytes(message , 'latin-1'), digestmod = hashlib.sha256).hexdigest().upper()

Example of using request with headers:

#Example, trying to get account's balance
curl -X GET https://api-stage.letsbit.io/api/v1/exchange/account/balances \
-H "X-Auth-Apikey: changeme" \
-H "X-Auth-Nonce: changeme" \
-H "X-Auth-Signature: changeme"

Expected response:

[
{
"balance": "1.4995",
"currency": "eth",
"locked": "0.0"
}
]