본문으로 건너뛰기

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) 가져오기​

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

M2M 애플리케이션은 액세스 토큰 (Access token)을 가져오기 위해 토큰 엔드포인트에 POST 요청을 보냅니다. 이때 HTTP 요청 엔티티 본문에 application/x-www-form-urlencoded 형식으로 다음 파라미터를 추가해야 합니다:

  • grant_type: 반드시 client_credentials로 설정해야 합니다.
  • resource: 접근하려는 리소스 (Resource)
  • scope: 접근 요청의 스코프 (Scope)

또한, 토큰 엔드포인트가 M2M 애플리케이션을 인증 (Authentication)할 수 있도록 요청 헤더에 M2M 애플리케이션의 자격 증명을 포함해야 합니다.

이는 요청의 Authorization 헤더에 Basic 인증 (Authentication) 형식으로 애플리케이션의 자격 증명을 포함하여 달성할 수 있습니다: {App ID}:{App Secret}를 base64로 인코딩한 후, Basic 접두사 뒤에 값을 설정합니다.

App ID와 App Secret은 M2M 애플리케이션의 상세 페이지에서 확인할 수 있습니다:

App ID와 App Secret

Logto Management API용 액세스 토큰 가져오기​

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

액세스 토큰을 사용하여 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에만 해당됩니다.

Logto Cloud는 시스템 안정성을 위해 테넌트 단위의 런타임 속도 제한을 적용합니다. 자세한 내용은 시스템 제한 - 속도 제한 섹션을 참고하세요.

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

Postman으로 M2M 액세스 토큰을 몇 분 만에 얻기