احراز هویت

اولین قدم برای اتصال به api‌های باسلام، پیاده سازی سازی استاندارد OAuth2 (opens in a new tab) در برنامه‌ شماست. بدین منظور ابتدا کلاینت خود را بسازید و پس از آن با هدایت کاربر به سایت باسلام دسترسی‌های لازم را از او بگیرید و سپس می‌توانید به عنوان وکیل کاربر به منابع تحت مالکیت او دسترسی داشته باشید. خلاصه فرایند به شکل زیر است:

ایجاد کلاینت

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

دریافت دسترسی از کاربر

مرحله اول: ساخت لینک اعطای دسترسی و انتقال کاربر به آن

به منظور دریافت دسترسی، می‌بایست کاربر به صفحه‌ی اعطای دسترسی در سایت باسلام منتقل شود. این عملیات می‌تواند بعد از کلیک کاربر روی دکمه‌ای در اپلیکیشن شما اتفاق بیفتد.
الگوی آدرس به شکل زیر می‌باشد:

https://basalam.com/accounts/sso?client_id=[client_id]&scope=[scope]&redirect_uri=[client_redirect_uri]&state=[state]

• client_id: آی‌دی کلاینت ایجاد شده در مرحله قبلی
• scope: رشته‌ای از دسترسی‌های درخواستی که با کاما "," یا فاصله جدا شده‌اند
• client_redirect_uri: آدرسی که کاربر بعد از اعطای دسترسی به آن هدایت می‌شود، این آدرس باید همان آدرسی باشد که در ایجاد کلاینت قرار داده‌اید
• state: یک رشته دلخواه که در درخواست‌های بعدی به کلاینت شما ارسال می‌شود

مرحله دوم: بازگشت کاربر به برنامه شما و دریافت توکن کاربر

بعد از تایید کاربر در مرحله اول، او به برنامه شما با الگوی زیر هدایت می‌شود:

[redirect_uri]?code=[code]&state=[state]

• redirect_uri: آدرسی برنامه شما
• code: کد یک‌بار مصرف ایجاد شده توسط سرویس احراز هویت به منظور دریافت توکن
• state: مقدار دلخواهی که در مرحله اول ارسال کرده‌اید

در این هنگام، برای دریافت توکن کاربر، می‌بایست درخواست زیر را به سرویس احراز هویت ارسال نمایید:

curl --request POST \
  --url https://auth.basalam.com/oauth/token \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
        "grant_type" : "authorization_code",
        "client_id" : "[client_id]",
        "client_secret" : "[client_secret]",
        "redirect_uri" : "[redirect_uri]",
        "code" : "[code]"
}'

• client_id: آی‌دی کلاینت شما (قابل دریافت از قسمت مدیریت کلاینت)
• client_secret: رمز اختصاص داده شده به کلاینت پس از ایجاد آن (قابل دریافت از قسمت مدیریت کلاینت)
• redirect_uri: آدرس برنامه شما
• code: کد دریافتی در کوئری پارامتر

در صورت صحیح بودن اطلاعات، پاسخ دریافتی به صورت زیر است:

{
	"token_type": "Bearer",
	"expires_in": 31622400,
	"access_token": "...",
	"refresh_token": "..."
}

• token_type: نوع توکن برگشتی، که نوع Bearer هست.
• expires_in: زمان معتبر بودن توکن به ثانیه
• access_token: توکن کاربر
• refresh_token: توکنی برای دریافت توکن جدید زمانی که توکن کاربر منقضی شده

مرحله سوم دریافت اطلاعات کاربر

در صورت نیاز برای اطمینان از صحت کد دریافتی می‌توانید رکوئست زیر را برای دریافت اطلاعات کاربر ارسال نمایید.

curl --request GET \
  --url https://auth.basalam.com/whoami \
  --header 'Authorization: Bearer [token]' \
  --header 'Content-Type: application/json' \
  --header 'accept: application/json'

• token: توکن (access_token) دریافتی در مرحله دوم

پاسخ دریافتی به شکل زیر است:

{
	"id": "...",      // آی‌دی کاربر
	"name": "....",     // نام کاربر
	"mobile": "09xxxxxxxxx",      // شماره همراه کاربر
	"hash_id": "xxx",     // هش‌آی‌دی کاربر
	"client": {
		"id": "...",
		"name": "...",
		"image_url": "..."
	},
}

احراز هویت کلاینت

برخی از api‌های ارائه شده، نیاز به احراز هویت کلاینت دارند. به عبارت دیگر این دست از api‌ها مربوط به کاربر نیستند بلکه توسط کلاینت مربوطه فراخوانی می‌شوند.
برای نمونه، به منظور مدیریت دلایل مصرف اعتبار در سرویس کیف پول، نیاز هست که کلاینت مربوطه احراز هویت شود.
بدین منظور، می‌بایست توکن مخصوص به کلاینت را از apiزیر دریافت کنید:

curl --request POST \
  --url https://auth.basalam.com/oauth/token \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
        "client_id" : "[client_id]",
        "client_secret" : "[client_secret]",
        "grant_type" : "client_credentials",
        "scope": "*"
}'

• client_id: آی‌دی کلاینت شما (قابل دریافت از قسمت مدیریت کلاینت)
• client_secret: رمز اختصاص داده شده به کلاینت پس از ایجاد آن (قابل دریافت از قسمت مدیریت کلاینت)

پاسخ دریافتی به شکل زیر است:

{
  "token_type": "Bearer",
  "expires_in": 31622400,
  "access_token": "..."
}