OAuth

OAuth 2.0 ให้แอปหรือแพลตฟอร์มของคุณทำงานแทนผู้ใช้ EasyDonate คนอื่นได้ โดยผู้ใช้กดปุ่ม "เชื่อมต่อ EasyDonate" แล้วยินยอมสิทธิ์แบบ scope ด้วยตัวเอง - ไม่ต้องแลกรหัสผ่านหรือ API key กัน

Flow เป็นแบบ Authorization Code + PKCE (บังคับใช้ PKCE ทุกกรณี)

ลงทะเบียน application

ไปที่ หน้าจัดการโซนผู้พัฒนาApplications สร้าง application เพื่อรับ client_id และ client_secret พร้อมตั้งค่า redirect_uri

ขั้นตอนทั้งหมด

1. พาผู้ใช้ไปหน้ายืนยันสิทธิ์

https://easydonate.app/oauth/authorize?client_id=<client_id>
  &redirect_uri=<your_callback>
  &scope=read:profile read:donations
  &state=<random>
  &code_challenge=<S256_challenge>
  &code_challenge_method=S256

2. รับ code ที่ callback ของคุณ

ผู้ใช้เข้าสู่ระบบและกดยินยอม จากนั้น EasyDonate จะ redirect ไปที่ redirect_uri?code=<code>&state=<state> - ตรวจว่า state ตรงกับค่าที่คุณ สร้างไว้ในขั้นตอนที่ 1 ก่อนไปต่อ

3. แลก code เป็น token จากฝั่ง backend ของคุณ

curl -X POST "https://example.com/oauth/token" \  -H "Content-Type: application/json" \  -d '{    "grant_type": "authorization_code",    "client_id": "string",    "client_secret": "string"  }'

Response:

{
  "access_token": "<jwt>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "ezdn_v1_rt_...",
  "scope": "read:profile read:donations"
}

access_token เป็น JWT ที่ถูกเซ็นแล้ว - ใส่ใน header Authorization ได้ตรง ๆ ส่วน refresh_token เป็น opaque string ขึ้นต้นด้วย ezdn_v1_rt_

4. เรียก API ด้วย access token

curl -X GET "https://example.com/api/v1/me"

5. Refresh เมื่อหมดอายุ

refresh token จะหมุนเวียนทุกครั้งที่ใช้ - เก็บตัวใหม่เสมอ

curl -X POST "https://example.com/oauth/token" \  -H "Content-Type: application/json" \  -d '{    "grant_type": "authorization_code",    "client_id": "string",    "client_secret": "string"  }'

6. เพิกถอน token (หรือถอดการเชื่อมต่อ)

curl -X POST "https://example.com/oauth/revoke" \  -H "Content-Type: application/json" \  -d '{    "token": "string",    "client_id": "string",    "client_secret": "string"  }'

อายุของ token

Access token มีอายุ 1 ชั่วโมง ส่วน refresh token มีอายุ 30 วัน โดย access token เป็น stateless JWT จึงเพิกถอนรายตัวไม่ได้ - หากต้องการตัดสิทธิ์แอปให้เพิกถอน refresh token (หรือถอดการเชื่อมต่อ) แทน

ลิมิตแอปที่ยังไม่ผ่านการยืนยัน

แอปที่ยังไม่ผ่านการยืนยัน (unverified) เชื่อมต่อผู้ใช้ได้สูงสุด 20 คน - ขอ verification ในหน้าจัดการเพื่อปลดลิมิต

เช็กลิสต์ความปลอดภัย

• ตรวจ state ที่ callback ทุกครั้งก่อนแลก code
• สร้าง code_verifier ใหม่ทุกรอบการขอสิทธิ์ และเก็บไว้ฝั่ง server
• เก็บ refresh_token ตัวใหม่ทุกครั้งหลัง refresh - ตัวเก่าจะใช้ไม่ได้ทันที
• ขอเฉพาะ scope ที่จำเป็น (ดู Scopes)