ทุกคำขอ Telm API ยืนยันตัวตนด้วยคีย์ APIที่ขึ้นต้นด้วย tk_live_ — ไม่ใช่ด้วยการล็อกอินแดชบอร์ดของคุณ สร้างคีย์ในบัญชีของคุณ ส่งมันในเฮดเดอร์ Authorization เป็น Bearer token และมันจะทำงานในนามบัญชีของคุณบนกลุ่มที่คุณเป็นแอดมิน หากคีย์รั่ว ให้เพิกถอนมันในแดชบอร์ดและออกคีย์ใหม่
1คีย์ API ทำงานอย่างไร
Telm REST API ไม่ใช้เซสชันเบราว์เซอร์ของคุณ แต่ละคำขอจะพกคีย์ APIแทน — สตริงลับยาว ๆ ที่ขึ้นต้นด้วยคำนำหน้า tk_live_ ตามด้วยอักขระสุ่ม คีย์ระบุบัญชีของคุณและอนุญาตการเรียก
คุณสร้างคีย์จากบัญชีของคุณและถือได้หลายคีย์พร้อมกัน (เช่น หนึ่งคีย์ต่อสคริปต์หรือบริการ) ความลับเต็มจะแสดงเพียงครั้งเดียว ณ เวลาสร้าง หลังจากนั้นแดชบอร์ดจะแสดงรายการคีย์ด้วยคำนำหน้าสั้น (tk_live_ บวกอักขระตัวแรก) เพื่อให้คุณจดจำมันได้ และค่าเต็มจะไม่ถูกเก็บไว้หลังจากนั้น
- คีย์มีลักษณะเป็น tk_live_ ตามด้วยสตริงสุ่มยาว
- คีย์ถูกสร้างและจัดการในแดชบอร์ดของคุณ
- ความลับเต็มแสดงเพียงครั้งเดียว — คัดลอกมันทันทีและเก็บไว้ในที่ปลอดภัย
- ปฏิบัติต่อคีย์เหมือนรหัสผ่าน คือ ใครก็ตามที่มีมันสามารถเรียก API ในนามคุณได้
2การส่งคีย์ไปกับทุกคำขอ
ส่งคีย์ในเฮดเดอร์ Authorizationโดยใช้รูปแบบ Bearer ค่าของเฮดเดอร์คือคำว่า Bearer เว้นวรรค แล้วตามด้วยคีย์ของคุณ — เช่น Authorization: Bearer tk_live_your_key_here
สำหรับไคลเอนต์ที่ตั้งค่าเฮดเดอร์ Authorization ได้ไม่สะดวก API ยังยอมรับคีย์ในเฮดเดอร์ X-API-Key ด้วย หากมีทั้งสองอย่าง เฮดเดอร์ Authorization จะชนะ คำขอผ่านสิ่งอื่นนอกจาก HTTPS จะไม่ถูกยอมรับในโหมดโปรดักชัน
- แนะนำ คือ ส่ง Authorization: Bearer tk_live_...
- ทางเลือก คือ ส่งคีย์ในเฮดเดอร์ X-API-Key แทน
- URL ฐานสำหรับทุกการเรียกคือ api.telm.com/api/public/v1
- ดูรายการ endpoint เต็มและ schema ได้ที่หน้านักพัฒนา
3คีย์เข้าถึงอะไรได้
คีย์ทำงานในนามบัญชีของคุณอย่างเคร่งครัด มันสามารถอ่านหรือเปลี่ยนเฉพาะกลุ่มที่บัญชีของคุณเป็นแอดมิน — คำขอที่มุ่งเป้าไปที่กลุ่มอื่นจะคืน 404 ดังนั้น API จึงไม่เคยเปิดเผยว่ากลุ่มที่คุณจัดการไม่ได้นั้นมีอยู่ด้วยซ้ำ
การเข้าถึงยังขึ้นกับแพ็กเกจของกลุ่มเป้าหมายด้วย endpoint ตรวจสอบสแปมเปิดให้ทุกแพ็กเกจภายในโควตารายวัน ในขณะที่ API เต็มรูปแบบ (กฎ การตั้งค่า whitelist บันทึก การวิเคราะห์ การตรวจสอบเป็นชุด และเว็บฮุก) พร้อมใช้บนแพ็กเกจ Pro ขึ้นไปบนกลุ่มที่เกี่ยวข้อง
- คีย์สามารถแตะเฉพาะกลุ่มที่คุณเป็นแอดมิน
- คำขอไปยังกลุ่มที่คุณไม่ได้จัดการจะคืน 404 ไม่ใช่ 403
- โควตารายวันถูกใช้ร่วมกันข้ามคีย์ทั้งหมดของคุณ นับต่อบัญชี
4การเพิกถอนและหมุนคีย์
หากคีย์ถูกเปิดเผย — คอมมิตลงคลัง วางลงในแชต หรือรั่วในทางอื่น — ให้เพิกถอนมันทันทีจากแดชบอร์ดของคุณ การเพิกถอนมีผลทันที คือ คีย์ที่ถูกเพิกถอนหยุดทำงานภายในไม่กี่วินาที ไม่ใช่หลังจากล่าช้าไประยะหนึ่ง
เนื่องจากโควตารายวันถูกใช้ร่วมกันต่อบัญชี การเพิกถอนคีย์หนึ่งไม่ได้รีเซ็ตตัวนับการใช้งานของคุณ การหมุนคีย์เป็นประจำเป็นสุขอนามัยที่ดี คือ สร้างคีย์ใหม่ นำไปใช้กับบริการของคุณ ยืนยันว่ามันทำงาน แล้วเพิกถอนคีย์เก่าเพื่อไม่ให้มีช่วงหยุดทำงาน
- เพิกถอนคีย์จากแดชบอร์ดของคุณ มันหยุดทำงานแทบจะทันที
- สร้างตัวแทนก่อน นำไปใช้ แล้วเพิกถอนคีย์เก่าเพื่อการหมุนแบบไม่มีช่วงหยุดทำงาน
- การเพิกถอนคีย์ไม่ได้รีเซ็ตโควตารายวันของคุณ — มันรีเซ็ตตอนเที่ยงคืน UTC
5ข้อผิดพลาดการยืนยันตัวตน
คีย์ที่หายไป ผิดรูปแบบ หรือถูกเพิกถอนจะคืน 401 พร้อมรหัสข้อผิดพลาดที่เครื่องอ่านได้และข้อความที่คนอ่านได้ หากคำขอของคุณเริ่มล้มเหลวด้วย 401 อย่างกะทันหัน ให้ตรวจสอบว่าคีย์ไม่ได้ถูกเพิกถอนและเฮดเดอร์ Authorization สะกดตรงเป๊ะเป็น Bearer บวกเว้นวรรคบวกคีย์
คีย์ที่ถูกต้องซึ่งมุ่งเป้าไปที่กลุ่มที่คุณไม่ได้จัดการจะคืน 404 คีย์ที่ถูกต้องบนแพ็กเกจต่ำกว่า Pro ซึ่งเรียก endpoint เฉพาะ Pro จะคืน 403 พร้อมรหัส plan_required และคำแนะนำให้อัปเกรด
- 401 — คีย์หายไป ผิดรูปแบบ หรือถูกเพิกถอน
- 404 — กลุ่มเป้าหมายไม่มีอยู่หรือคุณไม่ใช่แอดมินของมัน
- 403 plan_required — endpoint ต้องการ Pro ขึ้นไปบนกลุ่มนั้น