การอนุญาตบัญชี

สถานะการยืนยันตัวตน

คืนสถานะ flow การยืนยันตัวตนปัจจุบัน รวมถึง code, QR, Passkey, รหัสผ่าน, การ import session หรือยืนยันตัวตนแล้ว สำหรับ Passkey อาจเป็น passkey_required, passkey_pending, passkey_confirmation หรือ passkey_confirmation_sent โดย auth_payload.public_key มี WebAuthn challenge และ auth_payload อาจมีข้อความให้ยืนยัน ส่วน expires_at บอกเวลาที่ payload หมดอายุ

GEThttps://api.unifyport.ai/v1/accounts/{account_id}/auth

ช่องทางที่รองรับ

all

ก่อนเรียกใช้

ใช้ X-Api-Key ของ workspace เจ้าของทรัพยากรบนเซิร์ฟเวอร์ แทนค่าตัวอย่างทั้งหมดก่อนเรียกใช้

ที่มาของพารามิเตอร์

account_id: รับ data.id จากการสร้างหรือค้นหาบัญชี รหัสเป็นของ workspace ที่ระบุด้วย X-Api-Key ดูบัญชี

พารามิเตอร์คำขอ

ส่วนหัว

X-Api-Key

stringจำเป็น

API key ของพื้นที่ทำงาน ระบบจะระบุพื้นที่ทำงานจากส่วนหัวนี้

พารามิเตอร์ใน path

account_id

stringจำเป็น

ตัวระบุที่ใช้ใน route ของ authentication

เนื้อหาของคำขอ

จุดเชื่อมต่อนี้ไม่ต้องใช้เนื้อหา JSON

ทำความเข้าใจผลลัพธ์

อ่าน status/auth_status และ auth_payload ที่ส่งกลับจริงสำหรับคำสั่งยืนยันตัวตนนี้ หากต้องให้ผู้ใช้ดำเนินการ ให้ทำตามคู่มือช่องทาง authorized หมายถึงยืนยันตัวตนเสร็จ แต่ก่อนส่งข้อความต้องตรวจ runtime_status ด้วย

การตอบกลับ 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "account_id": "acc_example",
    "status": "awaiting_qr_scan",
    "auth_fields": [
      {
        "type": "qr_code",
        "required": true
      }
    ],
    "auth_payload": {
      "qr_code": "https://example.com/qr"
    },
    "expires_at": "2026-01-01T00:00:00Z",
    "last_error": ""
  }
}

เนื้อหาการตอบกลับ

account_id

string

บัญชีของผู้ให้บริการที่การตอบกลับนี้อ้างถึง

status

string

สถานะ flow การให้สิทธิ์ปัจจุบัน เช่น pending_auth, awaiting_qr_scan, awaiting_code, pending, passkey_required, passkey_pending, passkey_confirmation, passkey_confirmation_sent, authorized หรือ failed

auth_fields[]

object[]

อธิบายว่าขั้นตอนถัดไปต้องการอะไร — แต่ละรายการมี type และระบุว่าจำเป็นหรือไม่

type

string

ชนิดข้อมูลที่ขั้นตอนยืนยันตัวตนถัดไปต้องการ เช่น code หรือ password

required

boolean

ต้องระบุข้อมูลยืนยันตัวตนนี้หรือไม่

label

string

ป้ายชื่อช่องข้อมูลที่ provider ส่งมา หากมี

placeholder

string

ข้อความตัวอย่างในช่องข้อมูลที่ provider ส่งมา หากมี

auth_payload

object

payload มาตรฐานที่ต้องใช้ในขั้นปัจจุบัน QR ใช้ qr_code; ขั้นยืนยัน code ใช้ type=code; Passkey อาจคืน type=passkey และ public_key หรือ type=passkey_confirmation พร้อมข้อความให้ยืนยัน payload ของขั้นที่แยกกันจะไม่ปรากฏพร้อมกัน TikTok session อาจคืนคำขอให้สแกน QR หรือป้อนรหัสยืนยันเมื่อจำเป็นต้องโต้ตอบ HTTP 200 ไม่ได้หมายความว่าให้สิทธิ์สำเร็จ

expires_at

string

timestamp แบบ RFC3339 ที่หลังจากนั้น auth_payload ปัจจุบันจะไม่ใช้ได้แล้ว

format: date-time

last_error

string

ข้อผิดพลาดการยืนยันตัวตนล่าสุด หรือสตริงว่างเมื่อไม่มี

การตอบกลับ

200

200 OK

คำขอสำเร็จ ดูตัวอย่างเนื้อหาตอบกลับด้านบน

400

Bad Request

เนื้อหาของคำขอ path หรือพารามิเตอร์ไม่ถูกต้อง

401

Unauthorized

ส่วนหัว X-Api-Key หายไปหรือไม่ถูกต้อง

403

Forbidden

ระบบระบุคำขอได้ แต่ไม่อนุญาตให้ดำเนินการนี้

404

Not Found

ไม่พบทรัพยากรที่ร้องขอ โปรดตรวจสอบ error.code ร่วมกับการดำเนินการปัจจุบัน

500

Internal Server Error

บริการพบข้อผิดพลาดที่ไม่คาดคิด

เมื่อคำขอล้มเหลว

ตรวจ HTTP และ error.code/numeric_code เก็บ request_id แล้วแก้พารามิเตอร์ ยืนยันตัวตนต่อ หรือตรวจ runtime ตามสาเหตุ ตรวจผลครั้งก่อนก่อนส่งหรือเขียนซ้ำ อ้างอิงรหัสข้อผิดพลาด

อ่านสถานะ HTTP, error.code และ error.numeric_code ร่วมกับคำสั่งที่เรียก รหัสตัวเลขเป็นสตริง เก็บ request_id เพื่อตรวจปัญหา ค่านี้ไม่ใช่คีย์ป้องกันการทำซ้ำหรือรหัสงาน

invalid_request · 10000 · 400

ตรวจ JSON และฟิลด์ที่จำเป็น

เงื่อนไข: ใช้เมื่อเนื้อหาคำขอไม่ว่าง แต่ Content-Type ไม่ใช่ application/json

วิธีจัดการและลองใหม่: แก้พารามิเตอร์ตามคำสั่งและเงื่อนไขช่องทางก่อนเรียกใหม่ การส่งคำขอผิดแบบเดิมซ้ำไม่ช่วยแก้ข้อผิดพลาด

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 400 · 10000

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Content-Type must be application/json"
  }
}

invalid_target_workspace · 11003 · 400

เวิร์กสเปซเป้าหมายที่กำหนดทับว่างหรือรูปแบบไม่ถูกต้อง ให้ลบเฮดเดอร์กำหนดทับและใช้ API Key ของเวิร์กสเปซเป้าหมาย

เงื่อนไข: ใช้เมื่อคำขอมีเฮดเดอร์ X-Workspace-Id เพื่อระบุเวิร์กสเปซทับ

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 400 · 11003

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}

invalid_api_key · 11001 · 401

ตรวจว่า API Key ถูกต้องและเปิดใช้งานอยู่

วิธีจัดการและลองใหม่: เก็บ request_id และรหัสแบบมีโครงสร้าง ตรวจคำสั่งปัจจุบันก่อนเลือกการดำเนินการถัดไป

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 401 · 11001

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}

missing_api_key · 11000 · 401

เพิ่มส่วนหัว X-Api-Key

ตัวอย่าง · 401 · 11000

{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}

workspace_override_forbidden · 11002 · 403

คำขอพยายามระบุเวิร์กสเปซทับโดย API Key นี้ไม่มีสิทธิ์ ให้ลบเฮดเดอร์กำหนดทับและใช้ API Key ของเวิร์กสเปซเป้าหมาย

เงื่อนไข: ใช้เมื่อคำขอมีเฮดเดอร์ X-Workspace-Id เพื่อระบุเวิร์กสเปซทับ

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 403 · 11002

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}

target_workspace_not_found · 11004 · 404

ไม่พบเวิร์กสเปซที่กำหนดทับหรือใช้งานไม่ได้ ตรวจเจ้าของเวิร์กสเปซ ลบเฮดเดอร์กำหนดทับ และใช้ API Key ของเวิร์กสเปซเป้าหมาย การส่งซ้ำไม่เพิ่มสิทธิ์

เงื่อนไข: ใช้เมื่อคำขอมีเฮดเดอร์ X-Workspace-Id เพื่อระบุเวิร์กสเปซทับ

วิธีจัดการและลองใหม่: ตรวจรหัสเป้าหมาย เจ้าของทรัพยากร และเวิร์กสเปซปัจจุบัน อย่าถือว่าเป้าหมายที่ยืนยันแล้วว่าไม่มีหรือเข้าไม่ถึงเป็นความขัดข้องชั่วคราวที่ควรลองซ้ำอัตโนมัติ

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 404 · 11004

{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}

get_auth_state_failed · 20006 · 500

สถานะการยืนยันตัวตน: บริการไม่สามารถให้ผลการค้นหาที่ใช้ได้

วิธีจัดการและลองใหม่: เก็บ request_id และตรวจรหัสเป้าหมายกับสิทธิ์เข้าถึงของบัญชี ตรวจสาเหตุก่อนอ่านใหม่ การค้นหาล้มเหลวไม่ได้แปลว่าข้อมูลว่างหรือไม่มีทรัพยากร

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 500 · 20006

{
  "request_id": "req_example",
  "error": {
    "code": "get_auth_state_failed",
    "numeric_code": "20006",
    "message": "Failed to get account auth state"
  }
}

get_auth_state_failed · 20020 · 500

ตรวจ account_id และใช้ X-Api-Key ของเวิร์กสเปซเจ้าของบัญชี คีย์ปัจจุบันไม่สามารถเข้าถึงบัญชีที่ไม่พบในเวิร์กสเปซนี้

เงื่อนไข: ใช้เมื่อไม่พบบัญชี โดยคงสถานะ HTTP และ code ของคำสั่งเดิม และใช้ numeric_code ระบุว่าบัญชีไม่มีอยู่

JSON ตัวอย่าง โดย message เปลี่ยนตามสาเหตุจริง · 500 · 20020

{
  "request_id": "req_example",
  "error": {
    "code": "get_auth_state_failed",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}