API keys

หน้านี้สอนอะไร

การให้สคริปต์ แอปอื่น และผู้ช่วย AI มี key ของตัวเองสำหรับเรียก REST API โดยจำกัดเฉพาะ collection และสิ่งที่ต้องทำ

ควรอ่านก่อน: ผู้ใช้และการยืนยันตัวตน และ REST API

คน login ด้วยรหัสผ่านแล้วได้ session แต่สคริปต์ไม่ควรใช้รหัสผ่านของใคร ให้ใช้ API key แทน key เป็นของผู้ใช้คนหนึ่ง ทำได้ไม่เกินสิทธิ์ของผู้ใช้คนนั้น และจำกัดให้แคบลงได้อีก เช่น "อ่านและสร้างบทความได้ อย่างอื่นไม่ได้"

เปิดใช้

export default defineConfig({
  // …
  apiKeys: true,
})

จะมีหน้า API keys ใต้ ตั้งค่า ในหน้า admin และตารางสำหรับเก็บ key บน production ให้รัน easy-cms migrate:create api-keys แล้ว deploy migration

สร้าง key

1. ในหน้า admin เปิด ตั้งค่า → API keys แล้วกด สร้างใหม่
2. ตั้งชื่อที่บอกว่าใครใช้ ("ตัวนำเข้าจดหมายข่าว", "Claude")
3. ติ๊กสิ่งที่ key ทำได้ ทีละ collection และ global การติ๊กสร้าง แก้ไข ลบ หรือเผยแพร่ จะติ๊กอ่านให้ด้วย
4. ตั้งวันหมดอายุได้ (ไม่บังคับ) แล้วกด บันทึก

key จะแสดงครั้งเดียวในกล่องข้อความ ให้คัดลอกไปเก็บในค่าลับของแอปหรือโปรแกรมจัดการรหัสผ่าน Easy CMS เก็บไว้แค่ค่า hash ถ้า key หายจะแสดงอีกไม่ได้ ให้ลบแล้วสร้างใหม่

key มีรูปแบบ ecms_1a2b3c4d_… ส่วนหลัง ecms_ จะแสดงในรายการเป็น ขึ้นต้นด้วย เพื่อแยกว่าเป็น key ไหน

ใช้งาน

ส่ง key เป็น Bearer token ไม่ต้องใช้ cookie และ CSRF token:

curl https://example.com/api/cms/posts?draft=true \
  -H "Authorization: Bearer $EASY_CMS_KEY"

curl -X POST https://example.com/api/cms/posts \
  -H "Authorization: Bearer $EASY_CMS_KEY" \
  -H 'content-type: application/json' \
  -d '{"title":"Imported"}'

คำตอบ	เมื่อ
401 Invalid or expired API key	key ผิด ถูกลบ หมดอายุ หรือเจ้าของถูกปิดใช้งาน
403 This API key may not create "posts"	key ไม่ได้รับอนุญาตให้ทำสิ่งนั้น
403 Forbidden	key อนุญาต แต่กฎสิทธิ์ของเจ้าของไม่อนุญาต

key ทำอะไรได้บ้าง

แต่ละแถวในตารางคือ collection หรือ global แต่ละคอลัมน์คือการกระทำ:

การกระทำ	Collection	Global
อ่าน	ดูรายการและอ่านเอกสาร รวมฉบับร่าง	อ่าน
สร้าง	สร้างเอกสาร สำหรับ คลังสื่อ คือการอัปโหลดไฟล์	—
แก้ไข	แก้เอกสาร ดูประวัติ ย้อนกลับเวอร์ชัน	แก้
ลบ	ลบเอกสาร	—
เผยแพร่	เผยแพร่ ยกเลิกการเผยแพร่ และตั้งเวลา (collection ที่มี drafts)	เหมือนกัน

• key และเจ้าของตัดสินร่วมกัน key ทำให้สิทธิ์ของเจ้าของแคบลง แต่กฎสิทธิ์ของเจ้าของยังใช้อยู่ key ของ editor ที่ติ๊ก "ลบ" จะลบสิ่งที่ editor ลบไม่ได้ก็ไม่ได้
• ไม่ได้ติ๊กคือไม่อนุญาต รวมถึง collection ที่เพิ่มมาทีหลัง
• key เข้าถึงผู้ใช้และ key อื่นไม่ได้ collection เหล่านั้นไม่อยู่ในตาราง และ key สร้าง key ไม่ได้
• บันทึกเป็นฉบับร่างไม่ต้องมีสิทธิ์เผยแพร่ key ที่สร้างและแก้ได้แต่เผยแพร่ไม่ได้ จะเขียนฉบับร่างให้คนตรวจแล้วเผยแพร่

จัดการ key

• ใช้ล่าสุด บอกเวลาที่ key ถูกใช้ครั้งล่าสุด (อัปเดตอย่างมากนาทีละครั้ง)
• หมดอายุ หลังเวลานี้ key จะได้ 401
• เพิกถอน key ด้วยการลบ ใช้ไม่ได้ทันที
• การปิดใช้งาน (หรือลบ) ผู้ใช้จะทำให้ key ของคนนั้นใช้ไม่ได้ด้วย
• admin เห็นทุก key ผู้ใช้อื่นเห็นและจัดการได้เฉพาะของตัวเอง

ในโค้ด

สร้าง key จากสคริปต์หรือ seed ด้วย Local API ได้ key จะถูกคืนมาครั้งเดียว:

const { key } = await cms.createApiKey({
  name: 'Newsletter importer',
  user: admin.id, // เจ้าของ ถ้าเรียกด้วย { user, overrideAccess: false } จะเป็นผู้ใช้คนนั้น
  permissions: { collections: { posts: ['read', 'create'] } },
  expiresAt: '2027-01-01T00:00:00Z',
})

request ที่ใช้ key จะมี apiKey อยู่ใน user กฎสิทธิ์และ hook จึงแยกได้:

access: {
  // คนลบบทความได้ แต่ key ลบไม่ได้ ไม่ว่าจะติ๊กอะไรไว้
  delete: ({ user }) => !!user && !user.apiKey,
}

ความปลอดภัย

• ส่วนที่เป็นความลับคือ byte สุ่ม 32 ตัว Easy CMS เก็บค่า hash แบบ SHA-256 และเทียบค่าแบบใช้เวลาคงที่
• ดูแล key เหมือนรหัสผ่าน: เก็บใน environment variable หรือระบบจัดการความลับ อย่าใส่ในโค้ดหรือใน browser
• ให้แต่ละแอปมี key ของตัวเองที่มีสิทธิ์น้อยที่สุด และตั้งวันหมดอายุเมื่อทำได้ การเปลี่ยน key ทำโดยสร้าง key ใหม่ เปลี่ยนแอปไปใช้ แล้วลบ key เก่า

ขั้นต่อไป

• REST API: endpoint ทั้งหมดที่ key เรียกได้
• Plugins: plugin MCP ใช้ API key สำหรับผู้ช่วย AI