본문으로 건너뛰기

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 권한을 가진 읽기 전용 리소스이며, 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) 응답​

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

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

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

액세스 토큰 (Access token)으로 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는 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 액세스 토큰을 몇 분 만에 발급받기