# 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 ?

# Using UI (recommended option)

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

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

# 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 protected] password=changeme otp_code=000000

Example of response:

{
    "created_at": "2020-06-01T07:01:20Z",
    "csrf_token": "f5b36515a428328e199a",
    "data": "{\"language\":\"en\"}",
    "data_storages": [],
    "email": "[email protected]",
    "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"
}

3. Validate your session

http --session barong_session https://your.domain.com/api/v2/peatio/account/balances

4. 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"
}

5. Securely save Access Key and Secret Key

#How to use API key ?

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

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

2. 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}"