ขั้นตอนการสร้าง Client Token

Client Token คืออะไร?

Client Token เป็น Token ที่ใช้ยืนยันตัวตนของ Client User ในการเรียก API โดยมีคุณสมบัติดังนี้:

มีอายุ 24 ชั่วโมง — หลังหมดอายุต้องขอ Token ใหม่
ใช้ได้ 1 Token ต่อ Client User — ไม่ว่าจะจัดการกี่กิจการก็ใช้ Client Token ตัวเดียว
ใช้ร่วมกับ User Token — Client Token ระบุตัวตนของ Client User ส่วน User Token ระบุว่าจะทำงานกับกิจการใด

💡
Client User ที่ดูแลหลายกิจการ สามารถใช้ Client Token เพียงตัวเดียว และสลับ User Token ตามกิจการที่ต้องการจัดการ

ข้อมูลที่ต้องใช้ก่อนขอ Client Token

ข้อมูล	ใช้ทำอะไร	ได้จากที่ไหน
`connectId`	ใช้ระบุตัวตนของ Client User	ข้อมูลที่ PEAK ส่งให้
`password`	ใช้ยืนยันสิทธิ์ในการขอ Client Token	ข้อมูลที่ PEAK ส่งให้
`Time-Stamp`	เวลาที่ทำ Request	สร้างจากระบบของผู้เรียก API
`Time-Signature`	ลายเซ็นสำหรับยืนยัน Request	สร้างจาก `Time-Stamp` ด้วย HMAC-SHA1

⚠️
Application Code ไม่ใช่ค่าที่ใช้ยิง Create Client Token โดยตรง
การสร้าง Client Token ต้องใช้ connectId และ password ที่ PEAK ส่งให้

ข้อมูลที่เกี่ยวข้องกับ Token และการเรียก API

ข้อมูล	ใช้ทำอะไร	ใช้ตอนไหน	ได้จากที่ไหน
`connectId`	ใช้ระบุตัวตนของ Client User	ใช้ตอนขอ Client Token และใช้เป็น Secret Key สำหรับสร้าง `Time-Signature`	ข้อมูลที่ PEAK ส่งให้ทางอีเมล์
`password`	ใช้ยืนยันสิทธิ์ในการขอ Client Token	ใช้ตอนขอ Client Token	ข้อมูลที่ PEAK ส่งให้ทางอีเมล์
`Time-Stamp`	เวลาที่ทำ Request	ใช้ทั้งตอนขอ Client Token และตอนเรียก API อื่น ๆ	สร้างจากระบบของผู้เรียก API
`Time-Signature`	ลายเซ็นสำหรับยืนยัน Request	ใช้ทั้งตอนขอ Client Token และตอนเรียก API อื่น ๆ	สร้างจาก `Time-Stamp` ด้วย HMAC-SHA1
`Client Token`	ใช้ยืนยันตัวตนของ Client User	ใช้หลังจากเรียก Create Client Token สำเร็จ	ได้จาก Response ของ API Create Client Token
`User Token`	ใช้ระบุกิจการหรือผู้ใช้งาน PEAK ที่ต้องการจัดการ	ใช้ร่วมกับ Client Token ตอนเรียก API อื่น ๆ	ขอ/สร้างตามขั้นตอนที่ PEAK กำหนด เช่น API Own Use / ขั้นตอนขอ User Token

รูปแบบ Time-Stamp

Time-Stamp คือเวลาที่ทำ Request โดยใช้รูปแบบ:
และต้องเป็น UTC +0 เท่านั้น

yyyyMMddHHmmss

ตัวอย่าง: เวลาให้เป็น UTC+0 นะครับ

20160830072630

💡
หากใช้ Postman Collection ที่ PEAK ส่งให้ ระบบจะสร้าง TimeStamp ให้อัตโนมัติผ่าน Pre-request Script

วิธีสร้าง Time-Signature

Time-Signature คือค่า HMAC-SHA1 ที่สร้างจาก Time-Stamp โดยใช้ connectId เป็น Secret Key

Time-Signature = HMAC-SHA1(Time-Stamp, connectId)

ตัวอย่าง:

Time-Stamp: 20160830072630
Secret Key: connectId
Algorithm: HMAC-SHA1
Output: Time-Signature

Request Body

{
  "PeakClientToken": {
    "connectId": "{{ConnectionId}}",
    "password": "{{Password}}"
  }
}

พารามิเตอร์	Required	รายละเอียด
`PeakClientToken.connectId`	Yes	รหัสเชื่อมต่อที่ได้รับจาก PEAK
`PeakClientToken.password`	Yes	รหัสผ่านที่ได้รับจาก PEAK

ตัวอย่าง Response

{
  "PeakClientToken": {
    "token": "de59d8e2-81e9-4cf1-88a9-c82429e6b930",
    "resCode": "200",
    "resDesc": "Token Authorized"
  }
}

วิธีตรวจสอบว่าสร้าง Client Token สำเร็จ

หลังจากเรียก API แล้ว ให้ตรวจสอบ 3 จุดนี้:

จุดที่ตรวจสอบ	ค่าที่ควรได้
HTTP Status	`200 OK`
`PeakClientToken.token`	มีค่า Token ส่งกลับมา
`PeakClientToken.resCode`	`200`

หากครบทั้ง 3 ข้อ แสดงว่าสร้าง Client Token สำเร็จ และสามารถนำ Token ไปใช้เรียก API อื่น ๆ ได้

Rate Limit และคำแนะนำในการใช้งาน

API สำหรับขอ Client Token มี Rate Limit อยู่ที่:

10 requests ต่อนาที

⚠️
ไม่ควรขอ Client Token ใหม่ทุกครั้งที่เรียก API
แนะนำให้เก็บ Client Token ไว้ใช้ซ้ำจนกว่าจะหมดอายุ 24 ชั่วโมง

ควรทำ	ไม่ควรทำ
ขอ Client Token 1 ครั้ง แล้วเก็บไว้ใช้ซ้ำ	ขอ Client Token ใหม่ทุก API request
Refresh Token เมื่อใกล้หมดอายุ หรือได้รับ Auth Error	ยิงขอ Token ถี่ ๆ แบบไม่จำเป็น
จัดการ Token ในระบบ Backend หรือ Middleware	ฝัง Token ไว้ใน Frontend หรือ Client-side code

Common Issues

ปัญหา	สาเหตุที่เป็นไปได้	วิธีตรวจสอบ
ไม่ได้รับ Token	`connectId` หรือ `password` ไม่ถูกต้อง	ตรวจสอบค่าที่ได้รับจาก PEAK
ได้ Error เรื่อง Signature	`Time-Signature` สร้างไม่ถูกต้อง	ตรวจสอบว่าใช้ HMAC-SHA1 และใช้ `connectId` เป็น Secret Key ตรวจสอบเวลาเป็น UTC+0 หรือไม่
เรียก API อื่นไม่ได้	ยังไม่ได้ใส่ `Client-Token` หรือ `User-Token`	ตรวจสอบ Header ของ Request
Token ใช้ไม่ได้หลังเวลาผ่านไป	Client Token หมดอายุ	ขอ Client Token ใหม่
Postman ไม่บันทึก ClientToken	เลือก Environment ไม่ถูกต้อง หรือ Test Script ไม่ทำงาน	ตรวจสอบว่าเลือก Environment ถูกต้อง
ใช้ Application Code แล้วยิง API ไม่ผ่าน	เข้าใจผิดระหว่าง Application Code กับ password	Application Code ใช้เปิดไฟล์ ZIP/ใช้ตามขั้นตอนขอ User Token ส่วน Create Client Token ใช้ `connectId` และ `password`