API Access token

API Access Token คือตัวระบุที่ไม่ซ้ำกันซึ่งกำหนดให้กับโปรเจกต์ใดโปรเจกต์หนึ่งหรือหลายโปรเจกต์ในบัญชีของคุณ ใช้สำหรับยืนยันตัวตนบัญชีของคุณเพื่อจัดการโปรเจกต์ผ่าน API รวมถึงการแก้ไขบัญชี การส่งข้อความ การแก้ไขโปรเจกต์ เป็นต้น

ประเภทของ API Access token

Pushwoosh มี API Access Token สองประเภทที่แตกต่างกัน: Server และ Device

โทเค็นแต่ละประเภทจะใช้ได้เฉพาะในขอบเขต API ที่กำหนดไว้เท่านั้น จะเกิดข้อผิดพลาดในการยืนยันตัวตนหากใช้โทเค็นที่ไม่ถูกต้อง

Server API token

Server API token ใช้กับเมธอด API ทั้งหมด ยกเว้นเมธอดที่อยู่ภายใต้ Device API ควรใส่โทเค็นนี้ไว้ในส่วน body ของคำขอในฟิลด์ auth

Device API token

Device API token ใช้เฉพาะกับเมธอด Device API เท่านั้น ควรใส่โทเค็นนี้ไว้ในส่วน header ของคำขอ HTTP โดยใช้ Authorization header ด้านล่างนี้คือตัวอย่างรูปแบบ header ที่ถูกต้อง:

Authorization: Token <device_api_token>

แทนที่ <device_api_token> ด้วยค่า Device API Token ของคุณ

สร้างและจัดการ API Access token

คุณสามารถดู สร้าง และจัดการ API Access token ของคุณได้ในส่วน API Access ของ Pushwoosh Control Panel หากต้องการเข้าถึง ให้ไปที่ Settings → API Access โทเค็น Pushwoosh Demo App

โดยค่าเริ่มต้น แต่ละบัญชีจะมีโทเค็นที่ชื่อว่า Pushwoosh Demo App ซึ่งตั้งค่าเป็น server token

สร้าง API Access token ใหม่

หากต้องการสร้าง API Access token ใหม่:

ไปที่ส่วน API Access ใน Control Panel
คลิก Generate New Token
ในหน้าต่างที่ปรากฏขึ้น ให้เลือกประเภทโทเค็น:
- Server ใช้สำหรับเมธอด API ส่วนใหญ่ (ยกเว้นเมธอด Device API)
- Device ใช้สำหรับเมธอด Device API เท่านั้น
ป้อนชื่อสำหรับโทเค็น
คลิก Generate เพื่อสร้างโทเค็น

สร้างโทเค็นใหม่

สำคัญ: อย่าลืมให้สิทธิ์การเข้าถึงโทเค็นกับแอปที่ถูกต้องใน Pushwoosh Control Panel ของคุณ เรียนรู้เพิ่มเติม

โทเค็นใหม่จะปรากฏในรายการ API Access จากตรงนั้น คุณสามารถคัดลอกค่าเพื่อใช้ในคำขอ API หรือจัดการสิทธิ์การเข้าถึงได้ตามต้องการ

จัดการโทเค็น

หากต้องการจัดการ API token ที่มีอยู่ ให้คลิก เมนูสามจุด (⋮) ถัดจากรายการโทเค็นในส่วน API Access

จัดการโทเค็น

มีตัวเลือกดังต่อไปนี้:

Grant access to all projects

ให้สิทธิ์โทเค็นในการเข้าถึงโปรเจกต์ทั้งหมดในบัญชีของคุณ ซึ่งจะทำให้สามารถใช้ API ได้อย่างเต็มที่ในทุกโปรเจกต์

Revoke access from all projects

ลบสิทธิ์การเข้าถึงของโทเค็นในทุกโปรเจกต์ในบัญชีของคุณ โทเค็นจะไม่สามารถใช้ API ได้อีกจนกว่าจะได้รับสิทธิ์อีกครั้ง

Edit token

เปิดหน้าจอ Edit API Token Permissions ซึ่งคุณสามารถ:

เปลี่ยนชื่อโทเค็น
คัดลอกค่าโทเค็น
เลือกโปรเจกต์ที่โทเค็นสามารถเข้าถึงได้โดยการเลือกหรือยกเลิกการเลือกในรายการ
เปิดหรือปิดสิทธิ์ของโทเค็น: Account modification, Applications modification, Tags modification, Message sending & deleting
ตั้งค่า ที่อยู่ IP ที่อนุญาต ที่สามารถใช้โทเค็นได้ (เฉพาะ Server token)

แท็บ Permissions ยังแสดงเวลาที่ใช้โทเค็นล่าสุดและจำนวนครั้งที่การเรียกใช้ถูกปฏิเสธในช่วง 7 และ 30 วันที่ผ่านมา

หน้าจอแก้ไขโทเค็นพร้อมแท็บ Permissions และ Usage journal สรุปการใช้งาน และช่อง Allowed IP addresses

หลังจากทำการเปลี่ยนแปลงเสร็จแล้ว ให้คลิก Save เพื่อใช้การเปลี่ยนแปลง

Check a token’s usage journal

เปิดแท็บ Usage journal บนหน้าจอ Edit API Token Permissions เพื่อตรวจสอบการเรียก API ทุกครั้งที่ทำด้วยโทเค็นในช่วง 90 วันที่ผ่านมา เลือกผลลัพธ์ (Any outcome, Accepted, Completed, Refused: IP address, Refused: no rights) และช่วงวันที่ จากนั้นคลิก Apply เพื่อกรองรายการ คลิก Export CSV เพื่อดาวน์โหลดบันทึกที่กรองแล้วเป็นไฟล์ CSV

แท็บ Usage journal พร้อมตัวกรองผลลัพธ์และวันที่ และปุ่มส่งออก CSV

Delete token

ลบโทเค็นออกจากบัญชีของคุณอย่างถาวร

การให้สิทธิ์คำขอ API

ในการให้สิทธิ์คำขอ API ให้ใช้ API Access token ประเภทที่ถูกต้องตามประเภทของเมธอด API ที่คุณกำลังเรียกใช้:

สำหรับเมธอด Server API

ใส่โทเค็นในฟิลด์ “auth” ของ body คำขอ:

ตัวอย่าง:

{
  "request": {
    "application": "XXXXX-XXXXX",
    "auth": "yxoPUlwqm…………pIyEX4H", // วาง server token ของคุณที่นี่
    "notifications": [{
      "send_date": "now",
      "content": "Hello world"
    }]
  }
}

สำหรับเมธอด Device API

ใช้ Device token ใส่ไว้ใน header ของคำขอ HTTP โดยใช้รูปแบบต่อไปนี้:

Authorization: Token <device_api_token>

แทนที่ <device_api_token> ด้วยค่าโทเค็นจริงของคุณ

จำกัดโทเค็นไว้สำหรับที่อยู่ IP ที่ระบุ

Server token สามารถถูกจำกัดไว้สำหรับรายการที่อยู่ IP ต้นทางที่อนุญาต เมื่อตั้งค่ารายการแล้ว Pushwoosh จะยอมรับคำขอ API ที่ทำด้วยโทเค็นนั้นจากที่อยู่ที่ตรงกันเท่านั้น Device token ไม่มีตัวเลือกนี้

เปิด Edit token สำหรับ Server token และป้อนที่อยู่ใน Allowed IP addresses:

เพิ่มได้สูงสุด 50 รายการ เป็น IPv4 หรือ IPv6 โดยแต่ละรายการเป็นที่อยู่เดียว (203.0.113.7) หรือช่วง CIDR (203.0.113.0/24)
ที่อยู่เดียวจะถูกเก็บเป็นช่วงความยาวเต็ม เช่น 203.0.113.7 จะกลายเป็น 203.0.113.7/32
ช่วงจะถูกแปลงเป็นที่อยู่เครือข่ายตามรูปแบบมาตรฐาน เช่น 203.0.113.7/24 จะกลายเป็น 203.0.113.0/24
0.0.0.0/0 และ ::/0 จะถูกปฏิเสธ เนื่องจากจะตรงกับทุกที่อยู่และไม่มีการจำกัดใดๆ
เว้นว่างรายการไว้เพื่อให้โทเค็นสามารถใช้งานได้จากทุกที่อยู่ นี่คือค่าเริ่มต้นสำหรับโทเค็นที่มีอยู่และโทเค็นใหม่

คลิก Save เพื่อใช้รายการ การบันทึกจะถูกปฏิเสธหากรายการมีมากกว่า 50 รายการ หรือมีรายการที่ไม่ใช่ที่อยู่หรือช่วง CIDR ที่ถูกต้อง

จะเกิดอะไรขึ้นเมื่อมีคำขอมาจากที่อยู่ที่ไม่อนุญาต

Pushwoosh จะตรวจสอบที่อยู่ IP ที่อนุญาตในการเรียก API ทุกครั้งที่ทำด้วยโทเค็น ไม่ว่าจะเป็นการเรียก v1 REST (ตามที่ระบุไว้ในเอกสารอ้างอิง API นี้ เช่น Messages API), การเรียก Messaging API v2 หรือการเรียก Customer Journey API คำขอจากที่อยู่นอกรายการที่อนุญาตของโทเค็นจะถูกปฏิเสธ

รูปแบบการตอบสนองจะแตกต่างกันไปตามการเรียกที่คุณทำ:

การส่ง ยกเลิก และลบข้อความ เช่น createMessage, เมธอด create*Message เฉพาะช่องทาง, cancelMessage และ deleteMessage จะส่งคืน HTTP 200 พร้อม "status_code": 403 ใน body การตอบสนอง เช่นเดียวกับความล้มเหลวในการให้สิทธิ์อื่นๆ
การเรียก v1 REST อื่นๆ เช่น Applications, Tags, Geozones, Segmentation (Filters), Campaigns, Presets, Test devices และ Statistics APIs จะส่งคืน HTTP 403 จริงพร้อม body ข้อผิดพลาด JSON
Messaging API v2 และ Customer Journey API จะส่งคืน HTTP 403 พร้อมข้อผิดพลาด PermissionDenied