โต้ตอบกับ 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 ที่นิยมใช้งานบ่อยมีดังนี้:

• User
• Application
• Audit logs
• Roles
• Resources
• Connectors
• Organizations

หากต้องการดู 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 ของคุณ

ดึงโทเค็นการเข้าถึง

พื้นฐานเกี่ยวกับคำขอโทเค็นการเข้าถึง

แอป 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 ของคุณ:

ดึงโทเค็นการเข้าถึงสำหรับ Logto Management API

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

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

ข้อมูล:

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

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

ข้อมูล:

ตั้งแต่เวอร์ชัน v1.30.1 เป็นต้นไป Logto มี SDK Node.js อย่างเป็นทางการ @logto/api เพื่อช่วยให้คุณโต้ตอบกับ Logto Management API ได้ง่ายขึ้น

Node.js with `@logto/api` SDK

Logto Cloud

import { createManagementApi } from '@logto/api/management';

const { apiClient, clientCredentials } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const { value } = await clientCredentials.getAccessToken();
console.log('Access token:', value);

// หรือคุณสามารถข้ามขั้นตอนการขอโทเค็นการเข้าถึงและเรียก API ได้โดยตรง
const response = await apiClient.GET('/api/users');
console.log(response.data);

Self-hosted / OSS

ผู้ใช้ OSS ควรใช้ default เป็น tenant ID และต้องกำหนดค่า baseUrl และ apiIndicator ด้วย

const { apiClient, clientCredentials } = createManagementApi('default', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
  baseUrl: 'https://your.logto.endpoint',
  apiIndicator: 'https://default.logto.app/api',
});

Node.js

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(),
  });
};

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

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

ตัวอย่างการตอบกลับของโทเค็นการเข้าถึง (Access token response)

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

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

บันทึก:

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

cURL

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 response)

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

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

บันทึก:

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

เข้าถึง Logto Management API ด้วยโทเค็นการเข้าถึง

Node.js with `@logto/api` SDK

ด้วย @logto/api SDK คุณสามารถโต้ตอบกับ Management API ใด ๆ ได้โดยตรงโดยใช้โค้ดตัวอย่างด้านล่าง โทเค็นการเข้าถึง (Access token) จะถูกแคชภายในและรีเฟรชโดยอัตโนติหากจำเป็น

import { createManagementApi } from '@logto/api/management';

const { apiClient } = createManagementApi('your-tenant-id', {
  clientId: 'your-client-id',
  clientSecret: 'your-client-secret',
});

const response = await apiClient.GET('/api/applications');
console.log(response.data);

Node.js

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

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

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

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

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

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, การจับคู่แบบเป๊ะ และการแยกแยะตัวพิมพ์เล็ก-ใหญ่ โปรดดู คู่มือการค้นหาผู้ใช้ขั้นสูง

จัดการองค์กรด้วยตนเอง

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

เคล็ดลับการใช้ 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

ขีดจำกัดอัตรา

บันทึก:

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

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

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

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

รับโทเค็นการเข้าถึง M2M ภายในไม่กี่นาทีด้วย Postman