ภาพรวม Developer API
ยืนยันตัวตน เข้าใจ rate limit และจัดการโปรเจกต์กับ license key ของ workspace
Base URL
Developer API ให้บริการผ่าน edge host ของ Luaward:
https://api.luaward.com/v3ใช้ api.luaward.com สำหรับ API v3 ลิงก์ loader อยู่บน luaward.com และหน้ารับคีย์อยู่บน key.luaward.com ปัจจุบันยังไม่รองรับ custom domain
แพ็กเกจทางการสำหรับ JavaScript/TypeScript (npm @luaward/sdk), Python (PyPI luaward) และ CLI (npm @luaward/cli) เผยแพร่บน public registry แล้ว ดูคำสั่งติดตั้งและวิธีใช้ token ได้ที่ SDK และ CLI และ github.com/luaward ส่วน VS Code extension ยังไม่ได้ขึ้น Marketplace โปรดติดต่อทีมช่วยเหลือ เพื่อขอไฟล์ .vsix ที่ทดสอบแล้ว
สร้าง API key
เปิด Dashboard → API นักพัฒนา แล้วสร้าง key ที่มีชื่อ ระบบแสดง key เพียงครั้งเดียว Luaward เก็บแค่ค่า hash ของมัน จึงควรคัดลอกไปเก็บใน secret store ฝั่งเซิร์ฟเวอร์ อย่าใส่ใน script, browser bundle หรือ public repository
key เป็นของ workspace ไม่ใช่ของโปรเจกต์ใดโปรเจกต์หนึ่ง เหมือน key เดียวต่อบัญชีของ Luarmor: อ่านและแก้ได้ทุกโปรเจกต์ใน workspace และสร้างโปรเจกต์ใหม่ได้ หนึ่ง workspace มี key ที่ใช้งานอยู่ได้สูงสุด 10 key เฉพาะเจ้าของ workspace หรือแอดมินเท่านั้นที่สร้าง เพิกถอน หรือลบ key ได้ key ที่ถูกเพิกถอนจะหยุดทำงานทันที
ตอนสร้างคีย์ คุณเลือกได้ว่าคีย์ทำอะไรได้บ้าง: เต็มรูปแบบ (ทุกอย่าง ทั้งที่มีวันนี้และที่เพิ่มทีหลัง), จัดการคีย์ (อ่านได้ และสร้าง แก้ ลบ รีเซ็ต แบน ปลดแบน license key ของผู้เล่น) หรือ อ่านอย่างเดียว และยังจำกัดคีย์ให้เห็นแค่บางโปรเจกต์ได้ด้วย: คีย์นั้นจะเห็นเฉพาะโปรเจกต์เหล่านั้น (โปรเจกต์อื่นตอบ 404 PROJECT_NOT_FOUND เหมือนไม่มีอยู่) สถิตินับเฉพาะโปรเจกต์เหล่านั้น และสร้างโปรเจกต์ใหม่ไม่ได้ การเรียกที่คีย์ไม่มีสิทธิ์ทำจะได้ 403 INSUFFICIENT_SCOPE สิทธิ์และรายการโปรเจกต์กำหนดตอนสร้างคีย์ ถ้าจะเปลี่ยน ให้สร้างคีย์ใหม่แล้วเพิกถอนอันเก่า สคริปต์และระบบรับคีย์มี scope ของตัวเอง คือ scripts:write และ keysystem:write สิทธิ์เต็มรูปแบบรวมไว้ให้ ส่วนจัดการคีย์ไม่รวม
ยืนยันตัวตน
ส่ง developer key ใน Authorization header:
Authorization: Bearer YOUR_DEVELOPER_API_KEYAPI รับ header api-key ด้วย แต่ไม่รับ key ใน URL (เช่น query parameter) เพราะ URL จะไปอยู่ใน log
ข้อจำกัด
| เรื่อง | ข้อจำกัด |
|---|---|
| จำนวนคำขอต่อ key | 60 ครั้งต่อนาที เกินแล้วได้ HTTP 429 พร้อม header Retry-After |
| key ผิดจากที่อยู่เดียวกัน | 30 ครั้งต่อนาที จากนั้นที่อยู่นั้นต้องรอ 1 นาที (429) |
| ขนาด request body | ค่าเริ่มต้น 16 KiB; คำขอ source ของสคริปต์ 4 MiB; คำขอคีย์แบบ bulk 512 KiB ใหญ่กว่าลิมิตได้ 413 |
| license key | key ที่สร้างผ่าน API นับรวมกับลิมิตของแผนเดียวกับที่สร้างใน dashboard เมื่อเต็มลิมิต การสร้างจะได้ 403 พร้อม PLAN_LIMIT |
| โปรเจกต์ | โปรเจกต์ที่สร้างผ่าน API นับรวมกับลิมิตโปรเจกต์ของแผนในแบบเดียวกัน (403 พร้อม PLAN_LIMIT) |
IP ที่อนุญาต (Whitelist)
workspace กำหนดได้ว่า API เรียกจากที่อยู่ไหนบ้าง (Dashboard → API นักพัฒนา → IP ที่อนุญาต สูงสุด 20 ที่อยู่เต็มทั้ง IPv4 และ IPv6 พร้อมบันทึกช่วยจำ) รายการเดียวครอบคลุมทุก key และทุกโปรเจกต์ของ workspace ถ้าไม่มีรายการ ทุกที่อยู่เรียกได้ ถ้ามีรายการ เฉพาะที่อยู่เหล่านั้นเรียกได้ ไม่ว่าจะใช้ key ไหน ไม่รองรับช่วงอย่าง 10.0.0.0/8 และผู้เรียกที่อ่านที่อยู่ไม่ได้ถือว่าไม่อยู่ในรายการ หลังบันทึก แดชบอร์ดจะแสดงที่อยู่โดยซ่อนส่วนท้าย จึงควรใช้บันทึกช่วยจำเพื่อจำว่าเป็นของใคร การเปลี่ยนมีผลกับการเรียกครั้งถัดไป
เมื่อคำขอถูกปฏิเสธ
Error จะตอบ success: false, ข้อความ error และ code ที่โปรแกรมอ่านได้
| Status | Code | ความหมาย |
|---|---|---|
| 400 | INVALID_BODY, INVALID_FIELD | body ไม่ใช่ JSON หรือฟิลด์ผิดกติกา INVALID_FIELD มีรายการ details ที่ระบุฟิลด์แต่ละตัว |
| 400 | CONFIRM_REQUIRED | การลบโปรเจกต์ต้องส่งชื่อที่ตรงเป๊ะใน confirm_name |
| 401 | UNAUTHORIZED | ไม่มี key, key ผิด หรือถูกเพิกถอน |
| 403 | SUSPENDED | บัญชีเจ้าของ workspace ถูกระงับ |
| 403 | IP_NOT_ALLOWED | ที่อยู่ไม่อยู่ในรายการ IP ที่อนุญาตของ workspace |
| 403 | PLAN_LIMIT | workspace ถึงลิมิต key หรือโปรเจกต์ของแผนแล้ว |
| 403 | INSUFFICIENT_SCOPE | คีย์ไม่มีสิทธิ์ทำสิ่งนี้: เป็นแบบอ่านอย่างเดียว จัดการคีย์ได้แต่จัดการโปรเจกต์ไม่ได้ หรือถูกจำกัดบางโปรเจกต์แล้วพยายามสร้างโปรเจกต์ |
| 400 | BUILD_NOT_READY | เปิดให้บริการได้เฉพาะ build ที่เสร็จแล้ว |
| 403 | SCRIPT_LOCKED | Luaward ปิดสคริปต์นี้ไว้ เปิดที่นี่ไม่ได้ |
| 404 | SCRIPT_NOT_FOUND, BUILD_NOT_FOUND | ไม่มีสคริปต์นี้ในโปรเจกต์นี้ หรือไม่มี build นี้ของสคริปต์ |
| 404 | KEY_SYSTEM_NOT_FOUND, STEP_NOT_FOUND, BLOCK_NOT_FOUND | ไม่มีระบบรับคีย์ ด่าน หรือการบล็อกนี้ในโปรเจกต์นี้ |
| 409 | ALREADY_BLOCKED | บัญชี Discord นี้ถูกบล็อกบนหน้านี้อยู่แล้ว |
| 429 | TOO_MANY_BUILDS | workspace มี build รออยู่หลายอันแล้ว |
| 503 | UNAVAILABLE | API ติดต่อบริการที่เข้ารหัสโค้ดและ build ไม่ได้ |
| 503 | TEMPORARILY_UNAVAILABLE | บริการไม่พร้อมชั่วคราว รอตาม Retry-After: 30 ก่อนลองใหม่ |
| 404 | PROJECT_NOT_FOUND | ไม่พบโปรเจกต์นี้ใน workspace โปรเจกต์ของ workspace อื่น โปรเจกต์ที่ถูกลบ และ id ที่แต่งขึ้น ตอบเหมือนกันหมด |
| 404 | NOT_FOUND | ไม่พบ key นี้ในโปรเจกต์ |
| 409 | KEY_EXISTS | มี key ที่ค่าเดียวกันอยู่แล้ว |
| 409 | ALREADY_LINKED | คีย์ผูกกับบัญชี Discord อื่นอยู่แล้ว ส่ง force เพื่อแทนที่ |
| 413 | TOO_LARGE | body ใหญ่กว่าลิมิตของ endpoint นี้ |
| 429 | RATE_LIMIT | คำขอมากเกินไป หรือ key ผิดมากเกินไปจากที่อยู่เดียวกัน |
สิ่งที่ถูกบันทึก
การเปลี่ยนแปลงผ่าน API จะแสดงในประวัติของ license key โดยผู้กระทำคือ api: ตามด้วยชื่อ API key ได้แก่ created, extended, hwid_reset, banned, unbanned ประวัติของ key ที่ถูกลบจะหายไปพร้อม key จึงบันทึกการลบไว้ใน audit log ของ workspace แทน การสร้าง เปลี่ยนชื่อ และลบโปรเจกต์ก็บันทึกที่นั่นเช่นกัน และขึ้นในฟีดกิจกรรมของแดชบอร์ด คำตอบไม่ถูก cache เลย (Cache-Control: no-store)
Operation ที่รองรับ
API จัดการโปรเจกต์ สคริปต์ (โค้ด build และ kill switch) license key ทีละอันหรือจำนวนมาก และระบบรับคีย์ รวมทั้งอ่านสถิติ การรันล่าสุด audit log และสมาชิก ดู API Reference, API สคริปต์, คีย์จำนวนมากและการส่งออก, สถิติ การรัน และบันทึก และ API ระบบรับคีย์