Initial commit

2026-08-13 19:56:46 +03:30
commit de1d57a67b
474 changed files with 43185 additions and 0 deletions
--- a/docs/general/api-keys.md
+++ b/docs/general/api-keys.md
@@ -0,0 +1,142 @@
+# Barong API keys creation and usage
+
+This document explains how to create an API key on barong using the UI or command line tool.
+This API key can be used to access microservices in the cluster protected by barong authentication.
+You can find 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).
+
+![API-keys-section](../images/api-keys-1.jpeg)
+
+2. Create your API key and securely save Access Key and Secret Key
+
+![API-key-creation](../images/api-keys-2.jpeg)
+
+### Using API (use this option in case your frontend doesn't support API keys feature)
+
+1. Install [httpie](https://httpie.org/)
+
+2. Login into your account using httpie
+
+```bash
+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"
+}
+```
+
+3. Validate your session
+
+```bash
+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:
+
+```json
+{
+    "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:
+
+| 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)
+
+```bash
+date +%s%3N
+1584524005143
+```
+
+Nonce will be validated on server side to be not older than 5 seconds from the generation moment
+
+2. Calculate X-Auth-Signature header.
+
+X-Auth-Signature is HMAC-SHA256, calculated using concatenation of X-Auth-Nonce and Access Key.
+
+```ruby
+nonce = (Time.now.to_f * 1000).to_i.to_s # timestamp in milliseconds, ex: 1584524005143
+access_key = '61d025b8573501c2' # Access Key from 'How to create API key section ?'
+secret_key = '2d0b4979c7fe6986daa8e21d1dc0644f' # Secret Key from 'How to create API key section ?'
+OpenSSL::HMAC.hexdigest("SHA256", secret_key, nonce + access_key)
+# => "bd42b945e095880e28d046846dbecf655fdf09d95a396a24fe6fe1df42f15d13" 
+```
+
+3. Pass your headers in httpie (note `--session` is not needed anymore)
+
+```
+http https://your.domain.com/api/v2/peatio/account/balances \
+  "X-Auth-Apikey: 61d025b8573501c2" \
+  "X-Auth-Nonce: 1584524005143" \
+  "X-Auth-Signature: bd42b945e095880e28d046846dbecf655fdf09d95a396a24fe6fe1df42f15d13"
+```