โต้ตอบกับ 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: ขอบเขต (Scope) ของคำขอการเข้าถึง

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

วิธีนี้ทำได้โดยการแนบข้อมูลรับรองของแอปในรูปแบบ Basic authentication ใน request Authorization header: ให้ base64-encode {App ID}:{App Secret} และตั้งค่าเป็นค่าหลัง prefix Basic

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

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

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

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

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

ผลลัพธ์บางส่วนของ API อาจมีจำนวนมาก ระบบจะทำการแบ่งหน้า (pagination) Logto ให้ข้อมูล pagination อยู่ 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 เท่านั้น

Logto Cloud ใช้ขีดจำกัดอัตรา (rate limit) ระดับ tenant เพื่อปกป้องเสถียรภาพของระบบ ดูรายละเอียดได้ที่ system limit rate-limit section

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

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

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