การจัดการ API Token

ภาพรวม

API Token ใช้สำหรับการเข้าถึง Ocriva แบบ Programmatic เช่น การผสานรวม (Integration) กับระบบภายนอก สคริปต์อัตโนมัติ หรือแอปพลิเคชันของบุคคลที่สาม แทนการล็อกอินด้วย Username/Password ทุกครั้ง

Token แต่ละตัวมีสิทธิ์ (Permissions) และขอบเขต (Scopes) ที่กำหนดได้ วันหมดอายุ และรองรับการกำหนด IP Whitelist เพื่อจำกัดการเข้าถึงจากเครือข่ายที่เชื่อถือได้เท่านั้น

ประเภทของ API Token

ใช้ Organization Token สำหรับการผสานรวมระดับองค์กร และใช้ Project Token เมื่อต้องการจำกัดขอบเขตให้เล็กลงเพื่อความปลอดภัย

สิทธิ์ที่รองรับ

เมื่อสร้าง Token ต้องระบุอย่างน้อยหนึ่งสิทธิ์ (Permission) และขอบเขต (Scope):

Permissions:

• read — อ่านข้อมูลเท่านั้น
• write — สร้างและแก้ไขข้อมูล

Scopes ตัวอย่าง:

• templates — จัดการ Template
• documents — อัปโหลดและดูเอกสาร
• analytics — เข้าถึงข้อมูล Analytics
• billing — ดูข้อมูลการเรียกเก็บเงิน

วิธีสร้าง API Token

เฉพาะสมาชิกที่มีบทบาท Owner หรือ Admin เท่านั้นที่สร้าง Token ได้

1. ไปที่ Organization → API Tokens
2. คลิก Create Token
3. กรอกข้อมูล:
   • Name — ชื่อที่จดจำได้ เช่น Production Integration (สูงสุด 100 ตัวอักษร)
   • Description — อธิบายการใช้งาน (ไม่บังคับ สูงสุด 500 ตัวอักษร)
   • Type — organization หรือ project
   • Project — ระบุหากเลือก Type เป็น project
   • Permissions — เลือกสิทธิ์ที่ต้องการ
   • Scopes — เลือกขอบเขตที่ต้องการ
   • Expiry Date — วันหมดอายุ (ค่าเริ่มต้น: 1 ปีนับจากวันสร้าง)
   • IP Whitelist — รายการ IP หรือ CIDR ที่อนุญาต (ไม่บังคับ)
4. คลิก Create

รูปแบบ Token

Token ที่สร้างโดย Ocriva มีรูปแบบดังนี้:

ocr_<random_64_hex_characters>

ตัวอย่าง:

ocr_a1b2c3d4e5f6...

Prefix ocr_ ช่วยให้ระบุได้ทันทีว่าเป็น Ocriva API Token เมื่อพบใน Config หรือ Log

วิธีใช้ API Token

ส่ง Token ใน HTTP header ทุกคำขอที่ต้องการยืนยันตัวตน:

Authorization: Bearer ocr_<your_token_here>

ตัวอย่างด้วย cURL:

curl -H "Authorization: Bearer ocr_your_token_here" \
     https://api.ocriva.com/v1/templates

ตัวอย่างด้วย JavaScript (fetch):

const response = await fetch('https://api.ocriva.com/v1/templates', {
  headers: {
    'Authorization': `Bearer ${process.env.OCRIVA_API_TOKEN}`,
    'Content-Type': 'application/json',
  },
})

การดู Token และสถิติการใช้งาน

Token ที่สร้างแล้วสามารถดูได้ในหน้า API Tokens โดยระบบจะแสดง:

• ชื่อ Token และคำอธิบาย
• ประเภท (Organization / Project)
• สถานะ (Active / Inactive)
• สิทธิ์และขอบเขต
• วันหมดอายุ
• วันที่ใช้งานล่าสุด (lastUsedAt)
• จำนวนครั้งที่ใช้งาน (usageCount)
• IP ที่ใช้งานล่าสุด

การแก้ไขและปิดการใช้งาน Token

สมาชิกที่สร้าง Token และ Admin/Owner สามารถแก้ไข Token ได้:

• แก้ไขชื่อ/คำอธิบาย — อัปเดตได้ตลอดเวลา
• เปลี่ยน Permissions และ Scopes — ปรับขอบเขตสิทธิ์ได้
• เปลี่ยนวันหมดอายุ — ยืดหรือย่นอายุ Token
• ปิดการใช้งาน (Deactivate) — ตั้ง isActive: false เพื่อหยุดการใช้งานชั่วคราวโดยไม่ลบ
• เพิ่มหรือแก้ไข IP Whitelist — จำกัดหรือเปิดการเข้าถึงจาก IP เพิ่มเติม

การ Regenerate Token

หาก Token รั่วไหลหรือถูก Compromise ให้ Regenerate ทันที:

1. เปิดหน้ารายละเอียด Token
2. คลิก Regenerate
3. ค่า Token ใหม่จะถูกสร้างและแสดงครั้งเดียว
4. อัปเดต Config ทุกระบบที่ใช้ Token เดิม

การลบ Token

ลบ Token ที่ไม่ใช้งานแล้ว:

1. ไปที่หน้า API Tokens
2. คลิก Delete ถัดจาก Token ที่ต้องการลบ
3. ยืนยันการลบ

การลบเป็นการถาวร Token จะหยุดใช้งานได้ทันที

IP Whitelist

IP Whitelist จำกัดให้ Token ใช้งานได้เฉพาะจาก IP ที่ระบุเท่านั้น รองรับทั้ง IPv4, IPv6 และ CIDR notation:

192.168.1.1
10.0.0.0/8
2001:db8::/32

หากคำขอมาจาก IP ที่ไม่อยู่ใน Whitelist ระบบจะปฏิเสธแม้ Token จะถูกต้อง ใช้ฟีเจอร์นี้สำหรับ Integration กับ Server ที่มี IP คงที่เพื่อเพิ่มความปลอดภัย

แนวทางปฏิบัติด้านความปลอดภัย

• อย่าฝัง Token ในซอร์สโค้ด — ใช้ Environment Variable หรือ Secret Manager เสมอ
• ตั้งวันหมดอายุที่สมเหตุสมผล — Token ที่ไม่มีวันหมดอายุสร้างความเสี่ยงหาก Compromise
• ให้สิทธิ์น้อยที่สุดที่จำเป็น — Token ที่ต้องการแค่อ่านข้อมูลไม่ควรมีสิทธิ์ write
• หมุนเวียน Token อย่างสม่ำเสมอ — Regenerate Token ทุก 6–12 เดือนหรือเมื่อเกิดข้อสงสัย
• ตรวจสอบ usageCount และ lastUsedAt — สังเกตการใช้งานที่ผิดปกติ
• ลบ Token ที่ไม่ใช้แล้ว — Token ที่ Active แต่ไม่ได้ใช้เป็นความเสี่ยงที่ไม่จำเป็น
• ใช้ IP Whitelist สำหรับ Server-to-Server — หาก Integration มาจาก Server ที่มี IP คงที่ให้กำหนด Whitelist เสมอ