ข้ามไปยังเนื้อหา
Sursa Developers

POST/oauth/token

ออกโทเค็น OAuth 2.0

oauth_token

เอนด์พอยต์ออกโทเค็นของ OAuth 2.0 (RFC 6749 หัวข้อ 3.2) grant_type: authorization_code แลกรหัสที่ใช้ได้ครั้งเดียวเป็นโทเค็นคู่ และต้องมี code_verifier (PKCE S256) refresh_token ออกโทเค็นคู่ใหม่แลกกับโทเค็นรีเฟรช และทำให้โทเค็นรีเฟรชก่อนหน้าใช้ไม่ได้ (การหมุนเวียน) การนำโทเค็นที่ใช้ไม่ได้แล้วมาใช้ซ้ำจะเพิกถอนทั้งสายโทเค็น client_credentials ออกโทเค็นในนามขององค์กร สำหรับแอป confidential เท่านั้น โดยไม่มีโทเค็นรีเฟรช ไคลเอ็นต์ confidential ยืนยันตัวตนด้วยเฮดเดอร์ Authorization: Basic หรือด้วยฟิลด์ client_id และ client_secret ส่วนไคลเอ็นต์สาธารณะส่งเฉพาะ client_id โทเค็นเข้าถึง (access token) มีอายุ 1 ชั่วโมง โทเค็นรีเฟรช (refresh token) มีอายุ 90 วัน การตอบกลับและข้อผิดพลาดเป็นไปตาม RFC 6749 หัวข้อ 5 พร้อม Cache-Control: no-store เพิ่มใน 1.62.0

การยืนยันตัวตน

ไม่ต้องใช้ข้อมูลรับรอง

เนื้อหาคำขอ

application/x-www-form-urlencoded

ออบเจ็กต์: OAuthTokenRequest

  • grant_typestringจำเป็น

    ค่าที่ใช้ได้: authorization_coderefresh_tokenclient_credentials

  • codestring

    รหัสการอนุญาต (authorization_code)

  • redirect_uristring

    URI สำหรับเปลี่ยนเส้นทางเดียวกับในคำขอการอนุญาต (authorization_code)

  • code_verifierstring

    ค่า PKCE ต้นฉบับ ยาว 43 ถึง 128 อักขระ (authorization_code)

  • refresh_tokenstring

    โทเค็นรีเฟรช (refresh_token)

  • scopestring

    ขอบเขตสิทธิ์ที่คั่นด้วยช่องว่าง ใช้เพื่อจำกัดให้แคบลงเท่านั้น (refresh_token และ client_credentials)

  • client_idstring

    ID ของแอป เมื่อไม่ได้ส่งข้อมูลลับในเฮดเดอร์ Authorization: Basic

  • client_secretstring

    ข้อมูลลับของไคลเอ็นต์ของแอป confidential เมื่อไม่ได้ส่งในเฮดเดอร์ Authorization: Basic

การตอบกลับ

200ออกโทเค็นแล้ว

เฮดเดอร์การตอบกลับ

  • RateLimit-Policy

    ขีดจำกัดที่มีผล ในรูปแบบของร่าง IETF draft-ietf-httpapi-ratelimit-headers: รายการคั่นด้วยจุลภาค "<name>";q=<quota>;w=<window in seconds> โดย key คืออัตราคำขอของคีย์ API (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ user และเมื่อไม่มีข้อมูลรับรองคือ ip) ส่วน minute day และ month คือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTC

  • RateLimit

    ส่วนที่เหลือของแต่ละขีดจำกัดใน RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>

  • X-RateLimit-Limit

    ขีดจำกัดของรายการที่เข้มงวดที่สุดใน RateLimit-Policy (รายการที่เหลือคำขอน้อยที่สุด)

  • X-RateLimit-Remaining

    จำนวนคำขอที่เหลือภายใต้ขีดจำกัดที่เข้มงวดที่สุด

  • X-RateLimit-Reset

    จำนวนวินาทีจนกว่าขีดจำกัดที่เข้มงวดที่สุดจะรีเซ็ต

application/json

ออบเจ็กต์: OAuthTokenResponse

  • access_tokenstringจำเป็น

    โทเค็นเข้าถึง (kbat_…) สำหรับเฮดเดอร์ Authorization: Bearer

  • token_typestringจำเป็น

    ค่าที่ใช้ได้: Bearer

  • expires_inintegerจำเป็น

    อายุของโทเค็นเข้าถึงเป็นวินาที

  • refresh_tokenstring

    โทเค็นรีเฟรช (kbrt_…) ไม่มีสำหรับ client credentials

  • scopestringจำเป็น

    ขอบเขตสิทธิ์ของโทเค็นที่คั่นด้วยช่องว่าง

400ข้อผิดพลาดตามที่กำหนดใน RFC 6749 หัวข้อ 5.2

เฮดเดอร์การตอบกลับ

  • RateLimit-Policy

    ขีดจำกัดที่มีผล ในรูปแบบของร่าง IETF draft-ietf-httpapi-ratelimit-headers: รายการคั่นด้วยจุลภาค "<name>";q=<quota>;w=<window in seconds> โดย key คืออัตราคำขอของคีย์ API (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ user และเมื่อไม่มีข้อมูลรับรองคือ ip) ส่วน minute day และ month คือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTC

  • RateLimit

    ส่วนที่เหลือของแต่ละขีดจำกัดใน RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>

  • X-RateLimit-Limit

    ขีดจำกัดของรายการที่เข้มงวดที่สุดใน RateLimit-Policy (รายการที่เหลือคำขอน้อยที่สุด)

  • X-RateLimit-Remaining

    จำนวนคำขอที่เหลือภายใต้ขีดจำกัดที่เข้มงวดที่สุด

  • X-RateLimit-Reset

    จำนวนวินาทีจนกว่าขีดจำกัดที่เข้มงวดที่สุดจะรีเซ็ต

application/json

ออบเจ็กต์: OAuthErrorResponse

401ข้อมูลรับรองของไคลเอ็นต์ไม่ถูกต้อง (`invalid_client`)

เฮดเดอร์การตอบกลับ

  • RateLimit-Policy

    ขีดจำกัดที่มีผล ในรูปแบบของร่าง IETF draft-ietf-httpapi-ratelimit-headers: รายการคั่นด้วยจุลภาค "<name>";q=<quota>;w=<window in seconds> โดย key คืออัตราคำขอของคีย์ API (โควตาคือช่วงพุ่งสูง (burst) กรอบเวลาคือเวลาที่ใช้เติมกลับจนเต็ม สำหรับเซสชันคือ user และเมื่อไม่มีข้อมูลรับรองคือ ip) ส่วน minute day และ month คือโควตาขององค์กรสำหรับนาที วัน และเดือนตามปฏิทินใน UTC

  • RateLimit

    ส่วนที่เหลือของแต่ละขีดจำกัดใน RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>

  • X-RateLimit-Limit

    ขีดจำกัดของรายการที่เข้มงวดที่สุดใน RateLimit-Policy (รายการที่เหลือคำขอน้อยที่สุด)

  • X-RateLimit-Remaining

    จำนวนคำขอที่เหลือภายใต้ขีดจำกัดที่เข้มงวดที่สุด

  • X-RateLimit-Reset

    จำนวนวินาทีจนกว่าขีดจำกัดที่เข้มงวดที่สุดจะรีเซ็ต

application/json

ออบเจ็กต์: OAuthErrorResponse

การลองใหม่อย่างปลอดภัย

ส่งเฮดเดอร์ Idempotency-Key (เช่น UUID) ไปกับทุกคำขอ POST และ PATCH เมื่อลองใหม่ด้วยคีย์เดียวกันภายใน 24 ชั่วโมง Sursa จะส่งคืนการตอบกลับที่บันทึกไว้แทนการดำเนินการคำขอซ้ำ

ขีดจำกัดอัตราการเรียก

การตอบกลับมีเฮดเดอร์ RateLimit และ RateLimit-Policy รวมถึงเฮดเดอร์แบบเดิม X-RateLimit-Limit X-RateLimit-Remaining และ X-RateLimit-Reset การตอบกลับ 429 มี Retry-After เป็นวินาที ให้รอตามนั้นแล้วลองใหม่

← oauth · เอกสารอ้างอิง API