โต้ตอบกับ Management API

Logto Management API คืออะไร?

Logto Management API คือชุด API ที่ครอบคลุมซึ่งให้คุณควบคุมการใช้งานได้อย่างเต็มที่ตามความต้องการของผลิตภัณฑ์และเทคโนโลยีของคุณ โดยถูกสร้างไว้ล่วงหน้า แสดงอยู่ใน Console > API resources > Logto Management API และไม่สามารถลบหรือแก้ไขได้

ตัวระบุของมันจะอยู่ในรูปแบบ https://[tenant-id].logto.app/api

บันทึก:

ตัวระบุของ Logto Management API จะแตกต่างกันระหว่าง Logto Cloud และ Logto Open Source:

Logto Cloud: https://[tenant-id].logto.app/api
Logto OSS: https://default.logto.app/api

ในตัวอย่างต่อไปนี้ เราจะใช้ตัวระบุของเวอร์ชัน Cloud

ด้วย Logto Management API คุณสามารถเข้าถึงบริการ backend อันแข็งแกร่งของ Logto ซึ่งสามารถขยายได้สูงและนำไปใช้ได้ในหลากหลายสถานการณ์ โดยสามารถทำได้มากกว่าความสามารถ low-code ของ Admin Console

API ที่นิยมใช้งานบ่อยมีดังนี้:

หากต้องการดูรายละเอียด API เพิ่มเติม กรุณาเยี่ยมชม https://openapi.logto.io/

วิธีเข้าถึง Logto Management API

สร้างแอป M2M

บันทึก:

หากคุณยังไม่คุ้นเคยกับ flow การยืนยันตัวตนแบบ M2M (Machine-to-Machine) ขอแนะนำให้อ่าน ทำความเข้าใจ flow การยืนยันตัวตน เพื่อเข้าใจแนวคิดพื้นฐานก่อน

ไปที่ Console > Applications เลือกประเภทแอป “Machine-to-machine” และเริ่มกระบวนการสร้าง

ระหว่างกระบวนการสร้างแอป M2M คุณจะถูกนำไปยังหน้าที่คุณสามารถกำหนด บทบาท M2M ให้กับแอปพลิเคชันของคุณได้:

หรือคุณยังสามารถกำหนดบทบาทเหล่านี้ได้ที่หน้ารายละเอียดแอป M2M เมื่อคุณได้สร้างแอป M2M ไว้แล้ว:

ในโมดูลกำหนดบทบาท คุณจะเห็นบทบาท M2M ทั้งหมดถูกเพิ่มไว้แล้ว และบทบาทที่มีไอคอน Logto หมายถึงบทบาทเหล่านั้นมีสิทธิ์ Logto Management API อยู่ด้วย

ตอนนี้ให้กำหนดบทบาท M2M ที่มีสิทธิ์ Logto Management API ให้กับแอป M2M ของคุณ

ดึง access token

พื้นฐานเกี่ยวกับการขอ access token

แอป M2M จะส่งคำขอ POST ไปยัง token endpoint เพื่อดึงโทเค็นการเข้าถึง (Access token) โดยเพิ่มพารามิเตอร์ต่อไปนี้ในรูปแบบ application/x-www-form-urlencoded ใน entity-body ของ HTTP request:

grant_type: ต้องตั้งค่าเป็น client_credentials
resource: ทรัพยากรที่คุณต้องการเข้าถึง
scope: ขอบเขตของคำขอการเข้าถึง

และคุณยังต้องแนบข้อมูลรับรองของแอป M2M ของคุณใน request header เพื่อให้ token endpoint ทำการยืนยันตัวตนแอป M2M ของคุณ

สิ่งนี้ทำได้โดยการแนบข้อมูลรับรองของแอปในรูปแบบ Basic authentication ใน request Authorization header โดยที่ username คือ App ID และ password คือ App Secret

คุณสามารถค้นหา App ID และ App Secret ได้จากหน้ารายละเอียดของแอป M2M ของคุณ:

ดึง access token สำหรับ Logto Management API

Logto มี “Logto Management API” เป็นทรัพยากรในตัว ซึ่งเป็นทรัพยากรแบบอ่านอย่างเดียว (readonly) พร้อมสิทธิ์ all เพื่อเข้าถึง Logto Management API คุณสามารถดูได้จากรายการทรัพยากร API ของคุณ ตัวบ่งชี้ API ของทรัพยากรนี้จะอยู่ในรูปแบบ https://{your-tenant-id}.logto.app/api และนี่จะเป็นค่าทรัพยากรที่ใช้ใน body ของคำขอโทเค็นการเข้าถึง (Access token)

ก่อนเข้าถึง Logto Management API ให้แน่ใจว่าแอป M2M ของคุณได้รับมอบหมายบทบาท M2M ที่มีสิทธิ์ all จากทรัพยากร “Logto Management API” ที่มีอยู่ในระบบนี้แล้ว

ข้อมูล:

Logto ยังมีบทบาท M2M ที่ตั้งค่าล่วงหน้าไว้ชื่อ “Logto Management API access” สำหรับ tenant ที่สร้างใหม่ ซึ่งได้มอบหมายสิทธิ์ all ของทรัพยากร Logto Management API ไว้แล้ว คุณสามารถใช้งานได้ทันทีโดยไม่ต้องตั้งค่าสิทธิ์เอง บทบาทที่ตั้งค่าล่วงหน้านี้สามารถแก้ไขหรือลบได้ตามต้องการ

ตอนนี้ รวบรวมทุกอย่างที่เรามีและส่งคำขอ:

Node.js
cURL

const logtoEndpoint = 'https://your.logto.endpoint'; // แทนที่ด้วย Logto endpoint ของคุณ
const tokenEndpoint = `${logtoEndpoint}/oidc/token`;
const applicationId = 'your-application-id';
const applicationSecret = 'your-application-secret';
const tenantId = 'your-tenant-id';

const fetchAccessToken = async () => {
  return await fetch(tokenEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/x-www-form-urlencoded',
      Authorization: `Basic ${Buffer.from(`${applicationId}:${applicationSecret}`).toString(
        'base64'
      )}`,
    },
    body: new URLSearchParams({
      grant_type: 'client_credentials',
      resource: `https://${tenantId}.logto.app/api`,
      scope: 'all',
    }).toString(),
  });
};

curl --location \
  --request POST 'https://your.logto.endpoint' \
  --header 'Authorization: Basic ${your_auth_string}' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode 'resource=https://${tenantId}.logto.app/api' \
  --data-urlencode 'scope=all'

อย่าลืมแทนค่าตัวอย่างด้วยค่าจริงของคุณเอง

ข้อควรระวัง:

สำหรับผู้ใช้ Logto Cloud: เมื่อคุณโต้ตอบกับ Logto Management API คุณไม่สามารถใช้โดเมนที่กำหนดเองได้ ให้ใช้ Logto endpoint เริ่มต้น https://{your_tenant_id}.logto.app/oidc/token เพื่อขอรับโทเค็นการเข้าถึง

การตอบกลับ access token

ตัวอย่างการตอบกลับที่สำเร็จจะมีลักษณะดังนี้:

{
  "access_token": "eyJhbG...2g", // ใช้ token นี้เพื่อเข้าถึง Logto Management API
  "expires_in": 3600, // อายุของ token หน่วยเป็นวินาที
  "token_type": "Bearer", // ประเภทการยืนยันตัวตนสำหรับ request เมื่อใช้ access token
  "scope": "all" // scope `all` สำหรับ Logto Management API
}

บันทึก:

ขณะนี้ Logto ยังไม่รองรับการใช้แอป M2M เพื่อแทนผู้ใช้ sub ใน payload ของโทเค็นการเข้าถึง (access token) จะเป็น App ID

เข้าถึง Logto Management API ด้วย access token

คุณอาจสังเกตเห็นว่าการตอบกลับโทเค็นมีฟิลด์ token_type ซึ่งถูกกำหนดไว้เป็น Bearer เสมอ

ดังนั้น คุณควรใส่โทเค็นการเข้าถึง (Access token) ลงในฟิลด์ Authorization ของ HTTP headers โดยใช้รูปแบบ Bearer (Bearer YOUR_TOKEN) เมื่อคุณโต้ตอบกับเซิร์ฟเวอร์ทรัพยากร API ของคุณ

การใช้โทเค็นการเข้าถึง (Access token) ที่ร้องขอ กับทรัพยากร Management API ที่มีอยู่ใน Logto https://[your-tenant-id].logto.app/api เพื่อดึงข้อมูลแอปพลิเคชันทั้งหมดใน Logto:

Node.js
cURL

const logtoEndpoint = 'https://your.logto.endpoint'; // แทนที่ด้วย Logto endpoint ของคุณ
const accessToken = 'eyJhb...2g'; // Access Token

const fetchLogtoApplications = async () => {
  return await fetch(`${logtoEndpoint}/api/applications`, {
    method: 'GET',
    headers: {
      Authorization: `Bearer ${accessToken}`,
    },
  });
};

curl --location \
  --request GET 'https://your.logto.endpoint/api/applications' \
  --header 'Authorization: Bearer eyJhbG...2g'

อย่าลืมแทนที่ค่าตัวอย่างด้วยค่าของคุณเอง ค่าหลัง Bearer ควรเป็นโทเค็นการเข้าถึง (JWT) ที่คุณได้รับ

กรณีการใช้งาน Logto Management API ที่พบบ่อย

นักพัฒนาของเราได้สร้างฟีเจอร์เพิ่มเติมมากมายโดยใช้ Logto Management API เราเชื่อว่า API ของเราสามารถขยายได้สูงและรองรับความต้องการที่หลากหลายของคุณ ตัวอย่างต่อไปนี้คือกรณีที่ไม่สามารถทำได้ผ่าน Logto Admin Console แต่สามารถทำได้ผ่าน Logto Management API

สร้างโปรไฟล์ผู้ใช้เอง

ขณะนี้ Logto ยังไม่มี UI สำเร็จรูปสำหรับโปรไฟล์ผู้ใช้ เราตระหนักว่าโปรไฟล์ผู้ใช้เกี่ยวข้องกับธุรกิจและคุณสมบัติของผลิตภัณฑ์อย่างใกล้ชิด ในขณะที่เรากำลังหาวิธีที่ดีที่สุด ขอแนะนำให้ใช้ API ของเราเพื่อสร้างโซลูชันของคุณเอง เช่น คุณสามารถใช้ interaction API, profile API และ verification code API เพื่อพัฒนาโซลูชันที่ตรงกับความต้องการของคุณ

ค้นหาผู้ใช้ขั้นสูง

Logto Admin Console รองรับการค้นหาและกรองขั้นพื้นฐาน สำหรับตัวเลือกการค้นหาขั้นสูง เช่น การค้นหาแบบ fuzzy, การจับคู่แบบเป๊ะ และการแยกแยะตัวพิมพ์เล็ก-ใหญ่ ดูคู่มือ Advanced User Search ของเรา

จัดการองค์กรเอง

หากคุณใช้ฟีเจอร์ organizations เพื่อสร้างแอปหลายผู้เช่า คุณอาจต้องใช้ Logto Management API สำหรับงานเช่น การเชิญองค์กรและการจัดการสมาชิก สำหรับ SaaS ของคุณที่มีทั้งผู้ดูแลและสมาชิกใน tenant, Logto Management API จะช่วยให้คุณสร้าง admin portal ที่ปรับแต่งได้ตามความต้องการธุรกิจ ดูรายละเอียดเพิ่มเติมได้ที่ ที่นี่

เคล็ดลับการใช้ Logto Management API

การจัดการผลลัพธ์ API แบบแบ่งหน้า

ผลลัพธ์บางส่วนของ API อาจมีข้อมูลจำนวนมาก ผลลัพธ์เหล่านี้จะถูกแบ่งหน้า Logto ให้ข้อมูลการแบ่งหน้า 2 แบบ

ใช้ link headers

ตัวอย่าง header ของผลลัพธ์แบบแบ่งหน้าจะเป็นดังนี้:

Link: <https://logto.dev/users?page=1&page_size=20>; rel="first"

link header จะให้ URL สำหรับหน้าก่อนหน้า ถัดไป แรก และสุดท้ายของผลลัพธ์:

URL สำหรับหน้าก่อนหน้าจะตามด้วย rel="prev"
URL สำหรับหน้าถัดไปจะตามด้วย rel="next"
URL สำหรับหน้าสุดท้ายจะตามด้วย rel="last"
URL สำหรับหน้าแรกจะตามด้วย rel="first"

ใช้ total-number header

นอกจาก link headers มาตรฐานแล้ว Logto จะเพิ่ม header Total-Number ด้วย:

Total-Number: 216

ซึ่งจะสะดวกและมีประโยชน์มากสำหรับการแสดงหมายเลขหน้า

เปลี่ยนหมายเลขหน้าและขนาดหน้า

มี query parameter ที่เป็นตัวเลือก 2 ตัว:

page: ระบุหมายเลขหน้า เริ่มจาก 1 ค่าเริ่มต้นคือ 1
page_size: ระบุจำนวนรายการต่อหน้า ค่าเริ่มต้นคือ 20

ขีดจำกัดอัตรา (Rate limit)

บันทึก:

ใช้เฉพาะกับ Logto Cloud เท่านั้น

เพื่อความน่าเชื่อถือและความปลอดภัยของบริการสำหรับผู้ใช้ทุกคน เราใช้ firewall ทั่วไปเพื่อตรวจสอบและจัดการทราฟฟิกไปยังเว็บไซต์ของเรา แม้ว่าเราจะไม่ได้กำหนดขีดจำกัดอัตราอย่างเข้มงวด แต่ขอแนะนำให้ผู้ใช้จำกัดกิจกรรมไว้ที่ประมาณ 200 คำขอทุก 10 วินาที เพื่อหลีกเลี่ยงการกระตุ้นมาตรการป้องกันของเรา

ใช้ Logto Management API: คู่มือทีละขั้นตอน

รับ M2M access token ภายในไม่กี่นาทีด้วย Postman

Logto Management API คืออะไร?​

วิธีเข้าถึง Logto Management API​

สร้างแอป M2M​

ดึง access token​

พื้นฐานเกี่ยวกับการขอ access token​

ดึง access token สำหรับ Logto Management API​

การตอบกลับ access token​

เข้าถึง Logto Management API ด้วย access token​

กรณีการใช้งาน Logto Management API ที่พบบ่อย​

สร้างโปรไฟล์ผู้ใช้เอง​

ค้นหาผู้ใช้ขั้นสูง​

จัดการองค์กรเอง​

เคล็ดลับการใช้ Logto Management API​

การจัดการผลลัพธ์ API แบบแบ่งหน้า​

ใช้ link headers​

ใช้ total-number header​

เปลี่ยนหมายเลขหน้าและขนาดหน้า​

ขีดจำกัดอัตรา (Rate limit)​

แหล่งข้อมูลที่เกี่ยวข้อง​

Logto Management API คืออะไร?

วิธีเข้าถึง Logto Management API

สร้างแอป M2M

ดึง access token

พื้นฐานเกี่ยวกับการขอ access token

ดึง access token สำหรับ Logto Management API

การตอบกลับ access token

เข้าถึง Logto Management API ด้วย access token

กรณีการใช้งาน Logto Management API ที่พบบ่อย

สร้างโปรไฟล์ผู้ใช้เอง

ค้นหาผู้ใช้ขั้นสูง

จัดการองค์กรเอง

เคล็ดลับการใช้ Logto Management API

การจัดการผลลัพธ์ API แบบแบ่งหน้า

ใช้ link headers

ใช้ total-number header

เปลี่ยนหมายเลขหน้าและขนาดหน้า

ขีดจำกัดอัตรา (Rate limit)

แหล่งข้อมูลที่เกี่ยวข้อง