احراز هویت

برای داده‌های عمومی هیچ اعتبارنامه‌ای لازم نیست. هر کاری که از طرف یک سازمان انجام شود، اعتبارنامه‌ای از همان سازمان می‌خواهد: یک کلید API، یا توکنی از یک کلاینت OAuth. هر دو را مالکان و مدیران سازمان در داشبورد صادر می‌کنند.

کلیدهای API

کلید API شکلی مانند brl_api_<id>_<secret> دارد. آن را به‌صورت توکن bearer بفرستید:

GET /v1/org/deals HTTP/1.1
Host: api.birlesa.com
Authorization: Bearer brl_api_01a1...

مدت اعتبار: ۱ تا ۳۶۶ روز (به‌طور پیش‌فرض ۹۰). برای تعویض کلید برنامه داشته باشید: کلید تازه را بسازید، آن را مستقر کنید و کلید قدیمی را باطل کنید.
فقط یک بار نمایش داده می‌شود: تنها هشی از آن، همراه با pepper، ذخیره می‌شود.
ابطال ظرف یک دقیقه همه‌جا اعمال می‌شود، و برای اقدام‌ها و خواندن سوابق سازمان بی‌درنگ.
افرادی که می‌روند: وقتی کسی سازمان را ترک کند یا دیگر مدیر نباشد، کلیدها و کلاینت‌های OAuth که ساخته است باطل می‌شوند و وب‌هوک‌هایی که راه انداخته است غیرفعال می‌شوند.

دسترسی‌ها

هر کلید داده‌های عمومی را می‌خواند. اینکه جز این چه کار دیگری می‌تواند بکند، هنگام صدور آن تعیین می‌شود:

دسترسی	اجازه می‌دهد
`needs:write`	ثبت فرصت‌های سازمان (REST و ابزار `submit_need` در MCP)
`rfqs:send`	استعلام قیمت از تأمین‌کنندگان برای فرصت‌های باز سازمان
`org:read`	خواندن سوابق خود سازمان در `/v1/org/...`
`signals:read`	شرکای اعتباری: خواندن نشانه‌های ریسک شرکت‌هایی که رضایت داده‌اند
`data:read`	خواندن محصولات داده‌ای که سازمان برایشان قرارداد دارد

به هر اتصال فقط همان دسترسی‌ای را بدهید که به کار می‌برد. کلیدی که دسترسی لازم را ندارد، پاسخ 403 با کد no_org_read می‌گیرد (یا کد معادل برای آن اقدام).

اعتبارنامهٔ کلاینت در OAuth 2.0 (client credentials)

برای اتصال‌های ماشین‌به‌ماشین که نباید کلید بلندمدت نگه دارند، در داشبورد یک کلاینت OAuth بسازید. یک client_id (یک UUID) و یک client_secret (brl_ocs_...، فقط یک بار نمایش داده می‌شود) می‌گیرید. آن‌ها را با یک توکن دسترسی مبادله کنید (RFC 6749 §4.4(در زبانه جدید باز می‌شود)):

POST /oauth/token HTTP/1.1
Host: api.birlesa.com
Content-Type: application/x-www-form-urlencoded
Authorization: Basic base64(client_id:client_secret)

grant_type=client_credentials&scope=org:read

{"access_token": "brl_api_01a1...", "token_type": "Bearer", "expires_in": 3600, "scope": "org:read"}

توکن یک کلید API است که یک ساعت اعتبار دارد. دقیقاً مثل یک کلید از آن استفاده کنید.
scope دسترسی‌های کلاینت را محدودتر می‌کند؛ اگر آن را نفرستید، همهٔ دسترسی‌ها را می‌گیرید. درخواست بیش از آنچه کلاینت دارد با invalid_scope رد می‌شود.
کلاینت می‌تواند client_id و client_secret را به‌جای HTTP Basic در بدنهٔ فرم هم بفرستد.
از هر کلاینت حداکثر ۲۰ توکن هم‌زمان معتبر است؛ توکن تازه بیش از این، قدیمی‌ترین را باطل می‌کند. توکن را تا کمی پیش از پایان expires_in در حافظه نگه دارید و برای هر فراخوانی توکن تازه نگیرید.
با ابطال یک کلاینت، توکن‌هایش هم باطل می‌شوند.
خطاها از RFC 6749 پیروی می‌کنند: invalid_client (401)، invalid_scope، unsupported_grant_type، invalid_request (400)، slow_down (429). پاسخ‌ها هرگز کش نمی‌شوند (Cache-Control: no-store).

افراد، نه کلیدها

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