Barong API keys creation and usage

This document explain how to create an API key on barong using the UI or command line tool. This API key can be used to access each micro-service in the cluster protected by barong authentication. Read below an example how to use the API key.

How to create API key ?

  1. Find API keys section (often located on profile page).

API-keys-section

  1. Create your API key and securely save Access Key and Secret Key

API-key-creation

Using API (use this option in case your frontend doesn't support API keys feature)

  1. Install httpie

  2. Login into your account using httpie

http --session barong_session https://your.domain/api/v2/barong/identity/sessions \
  email=your@email.com password=changeme otp_code=000000

Example of response: json { "created_at": "2020-06-01T07:01:20Z", "csrf_token": "f5b36515a428328e199a", "data": "{\"language\":\"en\"}", "data_storages": [], "email": "your@example.com", "labels": [ { "created_at": "2020-06-01T07:01:45Z", "key": "email", "scope": "private", "updated_at": "2020-06-01T07:01:45Z", "value": "verified" } ], "level": 5, "otp": true, "phones": [ { "country": "FR", "number": "33*****0471", "validated_at": "2020-06-01T07:03:18.000Z" } ], "profiles": [], "referral_uid": null, "role": "member", "state": "active", "uid": "IDAF1AED1A42", "updated_at": "2020-10-22T18:01:09Z" }

  1. Validate your session
http --session barong_session https://your.domain.com/api/v2/peatio/account/balances
  1. Create your API key
http --session barong_session https://your.domain.com/api/v2/barong/resource/api_keys \
  algorithm=HS256 totp_code=681757 x-csrf-token:f5b36515a428328e199a

Expected response:

{
    "algorithm": "HS256",
    "created_at": "2019-12-23T12:22:15Z",
    "kid": "61d025b8573501c2", // Access Key
    "scope": [],
    "secret": {
        "auth": null,
        "data": {
            "value": "2d0b4979c7fe6986daa8e21d1dc0644f" // Secret Key
        },
        "lease_duration": 2764800,
        "lease_id": "",
        "metadata": null,
        "renewable": false,
        "warnings": null,
        "wrap_info": null
    },
    "state": "active",
    "updated_at": "2019-12-23T12:22:15Z"
}
  1. Securely save Access Key and Secret Key

How to use API key ?

To authenticate using API key you need to pass next 3 headers:

Header Description
X-Auth-Apikey Access Key for API key (see 'How to create API key section ?')
X-Auth-Nonce Timestamp in milliseconds (can be passed as a string)
X-Auth-Signature HMAC-SHA256, calculated using concatenation of X-Auth-Nonce and Access Key
  1. Generate X-Auth-Nonce - unique string (e.g current unix timestamp)
date +%s%3N
1584524005143

Nonce will be validated on server side to be not older than 5 seconds from the generation moment

  1. Compute X-Auth-Signature header

X-Auth-Signature is computed using HMAC-SHA256 algorithm. The secret used is the nonce concatenated with the access key.

Here is an example of bash script generating a signature and doing an API call using curl. The hmac256 command used is provided by the GnuPG libcrypt.

host="your.domain.com"
access_key='61d025b8573501c2' # Access Key from 'How to create API key section ?'
secret_key='2d0b4979c7fe6986daa8e21d1dc0644f' # Secret Key from 'How to create API key section ?'
nonce=$(date +%s%3N)

signature=$(echo -n "${nonce}${access_key}" | hmac256 "${secret_key}")

curl "https://${host}/api/v2/peatio/account/balances" \
  -H "X-Auth-Apikey: ${access_key}" \
  -H "X-Auth-Nonce: ${nonce}" \
  -H "X-Auth-Signature: ${signature}"