본문으로 건너뛰기

Management API와 상호작용하기

Logto Management API란?​

Logto Management API는 개발자가 제품 요구 사항과 기술 스택에 맞게 구현을 완전히 제어할 수 있도록 하는 포괄적인 API 집합입니다. 이 API는 미리 구축되어 있으며, 콘솔 > API 리소스 > 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 리소스 Logto Management API 세부 정보

Logto Management API를 통해 Logto의 강력한 백엔드 서비스에 접근할 수 있으며, 이는 매우 확장 가능하고 다양한 시나리오에서 활용할 수 있습니다. Admin Console의 로우코드 기능으로는 불가능한 것들도 이 API로 가능합니다.

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

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

Logto Management API에 접근하는 방법​

M2M 앱 생성하기​

노트:

기계 간 (M2M) 인증 (Authentication) 플로우에 익숙하지 않다면, 먼저 인증 (Authentication) 플로우 이해하기를 읽고 기본 개념을 이해하는 것을 추천합니다.

콘솔 > 애플리케이션으로 이동하여 "기계 간" 애플리케이션 유형을 선택하고 생성 과정을 시작하세요.

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

M2M 역할 할당 모달

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

M2M 역할 할당 페이지

역할 할당 모듈에서는 모든 M2M 역할이 포함되어 있음을 볼 수 있으며, Logto 아이콘이 표시된 역할은 Logto Management API 권한이 포함된 역할임을 의미합니다.

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

액세스 토큰 (Access token) 가져오기​

액세스 토큰 (Access token) 요청의 기본 사항​

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용 액세스 토큰 (Access token) 가져오기​

Logto는 내장된 “Logto Management API” 리소스를 제공합니다. 이 리소스는 Logto Management API에 접근할 수 있는 all 권한 (Permission)이 부여된 읽기 전용 리소스입니다. API 리소스 목록에서 확인할 수 있습니다.
리소스 API 지표는 https://{your-tenant-id}.logto.app/api 형식이며, 이는 액세스 토큰 (Access token) 요청 본문에서 사용할 리소스 값입니다.

Logto Management API details

Logto Management API에 접근하기 전에, 반드시 M2M 앱에 이 내장 “Logto Management API” 리소스의 all 권한 (Permission)이 포함된 M2M 역할 (Role)이 할당되어 있어야 합니다.

정보:

Logto는 새로 생성된 테넌트에 대해 미리 구성된 “Logto Management API access” M2M 역할 (Role)을 제공합니다. 이 역할에는 이미 Logto Management API 리소스의 all 권한 (Permission)이 할당되어 있습니다. 별도의 권한 설정 없이 바로 사용할 수 있습니다. 이 미리 구성된 역할은 필요에 따라 수정 및 삭제할 수 있습니다.

이제 모든 준비가 끝났으니, 요청을 전송해봅시다:

정보:

v1.30.1 버전부터 Logto는 Logto Management API와 쉽게 상호작용할 수 있도록 공식 @logto/api Node.js 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);

// 또는 액세스 토큰 (Access token) 획득을 생략하고 바로 API 호출도 가능합니다
const response = await apiClient.GET('/api/users');
console.log(response.data);

셀프 호스팅 / OSS​

OSS 사용자는 테넌트 ID로 default를 사용해야 하며, 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',
});

액세스 토큰 (Access token)으로 Logto Management API 접근하기​

@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);

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는 2가지 유형의 페이지네이션 정보를 제공합니다.

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

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"로 표시됩니다.

total-number 헤더 사용하기​

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

Total-Number: 216

이 정보는 페이지 수를 표시할 때 매우 편리하고 유용합니다.

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

2개의 선택적 쿼리 파라미터가 있습니다:

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

속도 제한 (Rate limit)​

노트:

이 내용은 Logto Cloud에만 해당됩니다.

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

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

Postman으로 M2M 액세스 토큰 (Access token) 빠르게 얻기