본문으로 건너뛰기

Management API와 상호작용하기

Logto Management API란 무엇인가요?​

Logto Management API는 개발자가 제품 요구 사항과 기술 스택에 맞게 구현을 완전히 제어할 수 있도록 하는 포괄적인 API 세트입니다. 이는 사전 구축되어 있으며, Console > API 리소스 > Logto Management API에 나열되어 있으며 삭제하거나 수정할 수 없습니다.

그 식별자는 https://[tenant-id].logto.app/api 패턴을 따릅니다.

Logto Management API 리소스 Logto Management API 세부사항

Logto Management API를 사용하면 Logto의 강력한 백엔드 서비스에 액세스할 수 있으며, 이는 매우 확장 가능하고 다양한 시나리오에서 활용될 수 있습니다. 이는 Admin Console의 로우 코드 기능으로 가능한 것 이상의 기능을 제공합니다.

자주 사용되는 API는 다음과 같습니다:

사용 가능한 API에 대해 더 알고 싶다면 https://openapi.logto.io/ 를 방문하세요.

Logto Management API에 액세스하는 방법​

M2M 앱 생성하기​

노트:

기계 간 (M2M) 인증 흐름에 익숙하지 않다면, 기본 개념을 이해하기 위해 인증 흐름 이해하기를 먼저 읽어보시길 권장합니다.

Console > Applications로 이동하여 "Machine-to-machine" 애플리케이션 유형을 선택하고 생성 과정을 시작하세요.

M2M 앱 생성 과정에서, 애플리케이션에 M2M 역할을 할당할 수 있는 페이지로 이동하게 됩니다:

M2M 역할 할당 모달

또는 이미 M2M 앱이 생성되어 있다면, M2M 앱 상세 페이지에서 이러한 역할을 할당할 수도 있습니다:

M2M 역할 할당 페이지

역할 할당 모듈에서 모든 M2M 역할이 포함되어 있으며, Logto 아이콘으로 표시된 역할은 Logto Management API 권한을 포함하고 있음을 알 수 있습니다.

이제 M2M 앱에 Logto Management API 권한을 포함한 M2M 역할을 할당하세요.

액세스 토큰 가져오기​

액세스 토큰 요청의 기본 사항​

M2M 앱은 HTTP 요청 엔티티 본문에 application/x-www-form-urlencoded 형식으로 다음 매개변수를 추가하여 토큰 엔드포인트에 액세스 토큰을 가져오기 위해 POST 요청을 합니다:

  • grant_type: client_credentials로 설정해야 합니다
  • resource: 액세스하려는 리소스
  • scope: 액세스 요청의 스코프

또한, 토큰 엔드포인트가 M2M 앱을 인증할 수 있도록 요청 헤더에 M2M 앱의 자격 증명을 포함해야 합니다.

이는 요청 Authorization 헤더에 기본 인증 (Basic authentication) 형식으로 앱의 자격 증명을 포함하여 달성됩니다. 여기서 사용자 이름은 App ID이고, 비밀번호는 App Secret입니다.

M2M 앱의 세부 정보 페이지에서 App ID와 App Secret을 찾을 수 있습니다:

App ID and App Secret

Logto Management API를 위한 액세스 토큰 가져오기​

Logto는 내장된 "Logto Management API" 리소스를 제공합니다. 이는 Logto Management API에 접근하기 위한 all 권한을 가진 읽기 전용 리소스이며, API 리소스 목록에서 확인할 수 있습니다. 리소스 API 지표는 https://{your-tenant-id}.logto.app/api 형식으로 되어 있으며, 이는 액세스 토큰 요청 본문에서 사용되는 리소스 값이 됩니다.

Logto Management API 세부사항

Logto Management API에 접근하기 전에, M2M 앱이 이 내장된 "Logto Management API" 리소스에서 all 권한을 포함하는 M2M 역할이 할당되었는지 확인하세요.

정보:

Logto는 새로 생성된 테넌트에 대해 사전 구성된 "Logto Management API 접근" M2M 역할도 제공합니다. 이 역할에는 Logto Management API 리소스의 모든 권한이 이미 할당되어 있습니다. 수동으로 권한을 설정하지 않고 직접 사용할 수 있습니다. 이 사전 구성된 역할은 필요에 따라 편집 및 삭제할 수도 있습니다.

이제 모든 것을 조합하여 요청을 보내세요:

const logtoEndpoint = 'https://your.logto.endpoint'; // Logto 엔드포인트로 교체하세요
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 엔드포인트 https://{your_tenant_id}.logto.app/oidc/token을 사용하여 액세스 토큰을 부여받아야 합니다.

액세스 토큰 응답​

성공적인 액세스 응답 본문은 다음과 같습니다:

{
  "access_token": "eyJhbG...2g", // Logto Management API에 액세스하기 위해 이 토큰을 사용하세요
  "expires_in": 3600, // 토큰 만료 시간 (초 단위)
  "token_type": "Bearer", // 액세스 토큰을 사용할 때 요청의 인증 유형
  "scope": "all" // Logto Management API를 위한 스코프 `all`
}
노트:

Logto는 현재 M2M 앱이 사용자를 나타내는 것을 지원하지 않습니다. 액세스 토큰 페이로드의 sub는 앱 ID가 됩니다.

액세스 토큰을 사용하여 Logto Management API에 액세스하기​

토큰 응답에 token_type 필드가 있으며, 이는 Bearer로 고정되어 있음을 알 수 있습니다.

따라서 API 리소스 서버와 상호작용할 때 액세스 토큰을 Bearer 형식 (Bearer YOUR_TOKEN)으로 HTTP 헤더의 Authorization 필드에 넣어야 합니다.

Logto의 모든 애플리케이션을 가져오기 위해 내장된 Logto Management API 리소스 https://[your-tenant-id].logto.app/api와 함께 요청된 액세스 토큰 (Access token)을 사용하세요:

const logtoEndpoint = 'https://your.logto.endpoint'; // Logto 엔드포인트로 교체하세요
const accessToken = 'eyJhb...2g'; // 액세스 토큰

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

Logto Management API 사용의 일반적인 시나리오​

우리 개발자들은 Logto Management API를 사용하여 많은 추가 기능을 구현했습니다. 우리는 우리의 API가 매우 확장 가능하며 다양한 요구를 지원할 수 있다고 믿습니다. Logto Admin Console로는 불가능하지만 Logto Management API를 통해 달성할 수 있는 시나리오의 몇 가지 예를 소개합니다.

사용자 프로필을 직접 구현하기​

Logto는 현재 사용자 프로필에 대한 사전 구축된 UI 솔루션을 제공하지 않습니다. 사용자 프로필은 비즈니스 및 제품 속성과 밀접하게 연결되어 있음을 인식하고 있습니다. 최선의 접근 방식을 결정하는 동안, 우리의 API를 사용하여 자체 솔루션을 만드는 것을 제안합니다. 예를 들어, 상호작용 API, 프로필 API 및 인증 코드 API를 활용하여 요구에 맞는 맞춤형 솔루션을 개발할 수 있습니다.

Logto Admin Console은 기본적인 검색 및 필터링 기능을 지원합니다. 퍼지 검색, 정확한 일치 및 대소문자 구분과 같은 고급 검색 옵션에 대해서는 고급 사용자 검색 튜토리얼과 가이드를 확인하세요.

조직 관리를 직접 구현하기​

다중 테넌트 앱을 구축하기 위해 조직 기능을 사용하는 경우, 조직 초대 및 멤버 관리와 같은 작업에 Logto Management API가 필요할 수 있습니다. 테넌트에 관리자와 멤버가 모두 있는 SaaS 제품의 경우, Logto Management API를 사용하여 비즈니스 요구에 맞춘 맞춤형 관리자 포털을 만들 수 있습니다. 자세한 내용은 여기를 확인하세요.

Logto Management API 사용 팁​

페이지 매김된 API 응답 관리​

일부 API 응답에는 많은 결과가 포함될 수 있으며, 결과는 페이지 매김됩니다. Logto는 두 가지 종류의 페이지 매김 정보를 제공합니다.

페이지 매김된 응답 헤더는 다음과 같습니다:

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

링크 헤더는 이전, 다음, 첫 번째 및 마지막 페이지의 결과에 대한 URL을 제공합니다:

  • 이전 페이지의 URL은 rel="prev"로 표시됩니다.
  • 다음 페이지의 URL은 rel="next"로 표시됩니다.
  • 마지막 페이지의 URL은 rel="last"로 표시됩니다.
  • 첫 번째 페이지의 URL은 rel="first"로 표시됩니다.

총 숫자 헤더 사용​

표준 링크 헤더 외에도, Logto는 Total-Number 헤더를 추가합니다:

Total-Number: 216

이는 페이지 번호를 표시하는 데 매우 편리하고 유용합니다.

페이지 번호 및 페이지 크기 변경​

두 가지 선택적 쿼리 매개변수가 있습니다:

  • page: 페이지 번호를 나타내며, 1부터 시작하며 기본값은 1입니다.
  • page_size: 페이지당 항목 수를 나타내며, 기본값은 20입니다.

속도 제한​

노트:

이는 Logto Cloud에만 해당됩니다.

모든 사용자를 위한 서비스의 신뢰성과 보안을 보장하기 위해, 우리는 웹사이트로의 트래픽을 모니터링하고 관리하는 일반적인 방화벽을 사용합니다. 엄격한 속도 제한을 시행하지는 않지만, 보호 조치를 피하기 위해 사용자가 10초마다 약 200개의 요청으로 활동을 제한할 것을 권장합니다.

Logto Management API 사용: 단계별 가이드

Postman을 사용하여 M2M 액세스 토큰을 몇 분 안에 얻기