ساختن کلید API

با کلید API، سیستم شما بدون کنسول با رومو کار می‌کند. هر کلید دو نیمه دارد:

نیمه	کجا می‌ماند
کلید خصوصی	فقط روی سرور شما. هرگز جایی فرستاده نمی‌شود.
کلید عمومی	در کنسول رومو. با آن امضای درخواست‌های شما بررسی می‌شود.

رومو هیچ‌وقت کلید خصوصی شما را نمی‌بیند و نگه نمی‌دارد.

1. جفت کلید را بسازید

یکی از این چهار راه را بردارید. هر راه دو دستور دارد: اولی کلید را می‌سازد و دومی نیمه‌ی عمومی را به شکل یک متن 64 نویسه‌ای چاپ می‌کند. سه راه اول فایل romu-api-key.pem را می‌سازند؛ همان فایلی که کتابخانه‌های رومو می‌خوانند.

OpenSSL نسخه‌ی 1.1.1 یا تازه‌تر لازم است. OpenSSL قدیمی خود مک (LibreSSL) این کلید را نمی‌سازد؛ در مک یکی از راه‌های دیگر را بردارید.

openssl genpkey -algorithm ed25519 -out romu-api-key.pem && chmod 600 romu-api-key.pem

openssl pkey -in romu-api-key.pem -pubout -outform DER | tail -c 32 | xxd -p -c 64

Python نسخه‌ی 3.8 یا تازه‌تر، با کتابخانه‌ی cryptography⁠:

pip install cryptography

python3 -c "import os;os.umask(0o77);from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey as E;from cryptography.hazmat.primitives import serialization as s;open('romu-api-key.pem','wb').write(E.generate().private_bytes(s.Encoding.PEM,s.PrivateFormat.PKCS8,s.NoEncryption()))"

python3 -c "from cryptography.hazmat.primitives import serialization as s;k=s.load_pem_private_key(open('romu-api-key.pem','rb').read(),None);print(k.public_key().public_bytes(s.Encoding.Raw,s.PublicFormat.Raw).hex())"

Node.js نسخه‌ی 16 یا تازه‌تر؛ چیزی برای نصب لازم نیست.

node -e "const c=require('crypto');require('fs').writeFileSync('romu-api-key.pem',c.generateKeyPairSync('ed25519').privateKey.export({type:'pkcs8',format:'pem'}),{mode:0o600})"

node -e "const c=require('crypto');console.log(c.createPublicKey(require('fs').readFileSync('romu-api-key.pem')).export({type:'spki',format:'der'}).subarray(-32).toString('hex'))"

کتابخانه‌های رومو (romu.py⁠، romu.ts و romu.go⁠) کلیدی را که ssh-keygen می‌سازد نمی‌خوانند. اگر از آن‌ها استفاده می‌کنید، یکی از راه‌های دیگر را بردارید.

ssh-keygen -t ed25519 -f romu-api-key

cut -d' ' -f2 romu-api-key.pub | base64 -d | tail -c 32 | xxd -p -c 64

هر چهار راه برای یک کلید همان 64 نویسه را چاپ می‌کنند. یعنی کلیدی که با OpenSSL ساخته شده، با دستور دوم Python یا Node.js هم همان متن را می‌دهد.

2. کلید را در کنسول بگذارید

در کنسول به «کلیدهای API و Webhook» بروید و «کلید تازه» را بزنید. فقط مدیر سازمان این دکمه را می‌بیند.

فرم را پر کنید:

فیلد	چه بنویسید
نام	نامی که کلید را با آن بشناسید، مثلاً «سامانه‌ی فروش»
کلید عمومی Ed25519	همان متن 64 نویسه‌ای
دسترسی	کاری که کلید اجازه دارد بکند (پایین‌تر)
کیف پول‌ها	کیف پول‌هایی که کلید با آن‌ها کار می‌کند
آدرس‌های IP مجاز	IP سرورهای شما؛ دست‌کم یکی
مدت اعتبار	یک ماه، سه ماه، شش ماه یا یک سال

«پیشنهاد کلید» را بزنید. کنسول یک بار دیگر ورود شما را می‌پرسد.
تأییدکننده‌ها درخواست را در اپ رومو تأیید می‌کنند. دسترسی، IP و کیف پول‌های کلید را پیش از فرستادن، خودتان در فرم دوباره بخوانید. تا تأیید نشود، کلید کار نمی‌کند.
شناسه‌ی کلید، یعنی key_id⁠، از لحظه‌ی پیشنهاد در فهرست کلیدها هست. آن را به سیستم خودتان بدهید. در همان فهرست، «آخرین استفاده» و IP آن هم نشان داده می‌شود.

دسترسی‌ها

دسترسی	چه می‌کند	کیف پول لازم است؟
خواندن	کیف پول‌ها، تراکنش‌ها و قانون‌ها را می‌خواند.	نه
برداشت	برداشت می‌فرستد؛ تأیید آن همچنان با قانون‌ها و اپ رومو است.	بله
خواندن تأییدها	درخواست‌های تغییر و وضعیت تأییدها را می‌خواند.	نه
آدرس‌های واریز	آدرس واریز می‌سازد، برچسب می‌زند و بایگانی می‌کند، تا سقف پلن شما.	بله
جمع‌آوری	قانون جمع‌آوری را می‌نویسد و جمع‌آوری «همین الان» را می‌خواهد؛ مقصد را نمی‌تواند عوض کند.	بله

اگر کلید هیچ دسترسی‌ای نداشته باشد که کیف پول بخواهد و هیچ کیف پولی انتخاب نکنید، کلید همه‌ی کیف پول‌ها را می‌خواند.

آدرس‌های IP مجاز

درخواست فقط از این آدرس‌ها پذیرفته می‌شود. هر مورد یکی از این‌هاست:

نوشته	یعنی
`203.0.113.7`	فقط همین یک آدرس
`203.0.113.0/24`	همه‌ی آدرس‌های `203.0.113.0` تا `203.0.113.255`
`2001:db8::/32`	یک بازه‌ی IPv6

دست‌کم یک مورد و حداکثر 32 مورد.
«همه‌جا» (0.0.0.0/0 یا ⁠::/0) پذیرفته نمی‌شود.
بازه باید با اولین آدرس خودش نوشته شود: 203.0.113.0/24 درست است، 203.0.113.9/24 نه. کنسول بازه‌ی درست را خودش پیشنهاد می‌دهد.