Account API에 의한 계정 설정

Logto Account API란 무엇인가요

Logto Account API는 최종 사용자가 Management API를 거치지 않고 직접 API에 접근할 수 있는 포괄적인 API 세트입니다. 주요 특징은 다음과 같습니다:

직접 접근: Account API는 최종 사용자가 자신의 계정 프로필을 직접 접근하고 관리할 수 있도록 하며, Management API의 중계를 필요로 하지 않습니다.
사용자 프로필 및 아이덴티티 관리: 사용자는 이메일, 전화번호, 비밀번호와 같은 아이덴티티 정보를 업데이트하고 소셜 연결을 관리할 수 있는 기능을 포함하여 프로필과 보안 설정을 완전히 관리할 수 있습니다. MFA 및 SSO 지원은 곧 제공될 예정입니다.
글로벌 접근 제어: 관리자는 접근 설정을 완전히 제어할 수 있으며 각 필드를 사용자 정의할 수 있습니다.
원활한 인가: 인가가 그 어느 때보다 쉬워졌습니다! client.getAccessToken()을 사용하여 OP (Logto)에 대한 불투명 액세스 토큰을 얻고, 이를 Bearer <access_token> 형식으로 Authorization 헤더에 첨부하세요.

Logto Account API를 사용하면 Logto와 완전히 통합된 프로필 페이지와 같은 맞춤형 계정 관리 시스템을 구축할 수 있습니다.

다음은 자주 사용되는 사례입니다:

사용자 프로필 조회
사용자 프로필 업데이트
사용자 비밀번호 업데이트
이메일, 전화번호 및 소셜 연결을 포함한 사용자 아이덴티티 업데이트
MFA 요소 (인증) 관리
사용자 세션 관리
사용자 승인 앱 (권한) 관리

사용 가능한 API에 대해 더 알고 싶다면 Logto Account API Reference 및 Logto Verification API Reference를 방문하세요.

노트:

SSO 계정 보기 및 계정 삭제 기능은 현재 Logto Management API를 통해 제공됩니다. 구현 세부 사항은 Management API에 의한 계정 설정을 참조하세요.

Account API 활성화 방법

콘솔 > 로그인 및 계정 > 계정 센터로 이동하세요.

Account API는 기본적으로 꺼져 있으며, 접근 제어가 잠겨 있습니다. Account API 활성화를 토글하여 켜세요.

활성화되면 식별자, 프로필 데이터 및 타사 토큰 접근에 대한 필드별 권한을 구성하세요. 각 필드는 Off, ReadOnly, 또는 Edit을 지원하며, 기본값은 Off입니다.

보안 필드:
- 필드에는 기본 이메일, 기본 전화번호, 소셜 아이덴티티, 비밀번호 및 MFA가 포함됩니다.
- 최종 사용자가 이러한 필드를 편집하기 전에, 비밀번호, 이메일 또는 SMS를 통해 자신의 아이덴티티를 확인하여 10분 동안 유효한 인증 기록 ID를 얻어야 합니다. 인증 기록 ID 얻기를 참조하세요.
- MFA를 위한 WebAuthn 패스키를 사용하려면, 계정 센터와 로그인 경험이 패스키를 공유할 수 있도록 WebAuthn 관련 출처에 프론트엔드 앱 도메인을 추가하세요. 새 WebAuthn 패스키 연결을 참조하세요.
프로필 필드:
- 필드에는 사용자 이름, 이름, 아바타, 프로필 (기타 표준 프로필 속성) 및 사용자 정의 데이터가 포함됩니다.
- 최종 사용자는 추가 인증 없이 이를 편집할 수 있습니다.
비밀 금고:
- OIDC 또는 OAuth 소셜 및 엔터프라이즈 커넥터의 경우, Logto 비밀 금고는 인증 후 타사 액세스 및 리프레시 토큰을 안전하게 저장합니다. 앱은 사용자가 다시 로그인하지 않고도 Google 캘린더 이벤트 동기화와 같은 외부 API를 호출할 수 있습니다. Account API가 활성화되면 토큰 검색이 자동으로 가능합니다.
세션 관리:
- 활성화되면 사용자는 장치 정보 및 마지막 로그인 시간을 포함하여 자신의 활성 세션을 보고 관리할 수 있습니다. 사용자는 특정 장치에서 로그아웃하기 위해 세션을 취소할 수도 있습니다.
- 이 동일한 Sessions 필드 권한은 사용자 승인 앱 (권한) API (보기 및 권한 취소)를 제어합니다.
- 최종 사용자가 세션 관리에 접근하기 전에, 비밀번호, 이메일 또는 SMS를 통해 자신의 아이덴티티를 확인하여 10분 동안 유효한 인증 기록 ID를 얻어야 합니다. 인증 기록 ID 얻기를 참조하세요.

Account API 접근 방법

노트:

액세스 토큰에 적절한 권한이 있는지 확인하려면 Logto 구성에서 해당 스코프를 올바르게 구성했는지 확인하세요.

예를 들어, POST /api/my-account/primary-email API의 경우 email 스코프를 구성해야 하며, POST /api/my-account/primary-phone API의 경우 phone 스코프를 구성해야 합니다.

import { type LogtoConfig, UserScope } from '@logto/js';

const config: LogtoConfig = {
  // ...other options
  // 사용 사례에 맞는 적절한 스코프를 추가하세요.
  scopes: [
    UserScope.Email, // `{POST,DELETE} /api/my-account/primary-email` API용
    UserScope.Phone, // `{POST,DELETE} /api/my-account/primary-phone` API용
    UserScope.CustomData, // 사용자 정의 데이터 관리용
    UserScope.Address, // 주소 관리용
    UserScope.Identities, // 아이덴티티 및 MFA 관련 API용
    UserScope.Profile, // 사용자 프로필 관리용
    UserScope.Sessions, // 사용자 세션 및 앱 권한 관리용
  ],
};

액세스 토큰 가져오기

애플리케이션에서 SDK를 설정한 후, client.getAccessToken() 메서드를 사용하여 액세스 토큰을 가져올 수 있습니다. 이 토큰은 Account API에 접근하는 데 사용할 수 있는 불투명 토큰입니다.

공식 SDK를 사용하지 않는 경우, 액세스 토큰 발급 요청을 /oidc/token으로 할 때 resource를 비워야 합니다.

액세스 토큰을 사용하여 Account API 접근

Account API와 상호작용할 때 HTTP 헤더의 Authorization 필드에 Bearer 형식 (Bearer YOUR_TOKEN)으로 액세스 토큰을 포함해야 합니다.

다음은 사용자 계정 정보를 얻는 예입니다:

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

기본 계정 정보 관리

사용자 계정 정보 조회

사용자 데이터를 얻으려면 GET /api/my-account 엔드포인트를 사용할 수 있습니다.

curl https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>'

응답 본문은 다음과 같습니다:

{
  "id": "...",
  "username": "...",
  "name": "...",
  "avatar": "..."
}

응답 필드는 계정 센터 설정에 따라 다를 수 있습니다.

기본 계정 정보 업데이트

기본 계정 정보에는 사용자 이름, 이름, 아바타, 사용자 정의 데이터 및 기타 프로필 정보가 포함됩니다.

사용자 이름, 이름, 아바타 및 사용자 정의 데이터를 업데이트하려면 PATCH /api/my-account 엔드포인트를 사용할 수 있습니다.

curl -X PATCH https://[tenant-id].logto.app/api/my-account \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"username":"...","name":"...","avatar":"..."}'

familyName, givenName, middleName, nickname, profile (프로필 페이지 URL), website, gender, birthdate, zoneinfo, locale, address를 포함한 기타 프로필 정보를 업데이트하려면 PATCH /api/my-account/profile 엔드포인트를 사용할 수 있습니다.

curl -X PATCH https://[tenant-id].logto.app/api/my-account/profile \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"familyName":"...","givenName":"..."}'

식별자 및 기타 민감한 정보 관리

보안상의 이유로, Account API는 식별자 및 기타 민감한 정보를 포함하는 작업에 대해 추가적인 인가 계층을 요구합니다.

인증 기록 ID 얻기

먼저, 10분 만료 (TTL)와 함께 인증 기록 ID를 얻어야 합니다. 이는 민감한 정보를 업데이트하기 전에 사용자의 아이덴티티를 확인하는 데 사용할 수 있습니다. 이는 사용자가 비밀번호, 이메일 인증 코드 또는 SMS 인증 코드를 통해 자신의 아이덴티티를 성공적으로 확인하면, 인증 관련 데이터 (식별자, 자격 증명, 소셜 계정 연결 및 MFA)를 업데이트할 수 있는 10분의 시간이 주어진다는 것을 의미합니다.

인증 기록 ID를 얻으려면 사용자의 비밀번호를 확인하거나 사용자의 이메일 또는 전화로 인증 코드를 보내야 합니다.

사용자의 비밀번호 확인

curl -X POST https://[tenant-id].logto.app/api/verifications/password \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'

응답 본문은 다음과 같습니다:

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

사용자의 이메일 또는 전화로 인증 코드 보내기

노트:

이 방법을 사용하려면 이메일 커넥터를 구성하거나 SMS 커넥터를 구성하고, UserPermissionValidation 템플릿이 구성되어 있는지 확인해야 합니다.

이메일을 예로 들어, 새 인증 코드를 요청하고 인증 기록 ID를 얻으세요:

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

응답 본문은 다음과 같습니다:

{
  "verificationRecordId": "...",
  "expiresAt": "..."
}

인증 코드를 받은 후, 이를 사용하여 인증 기록의 인증 상태를 업데이트할 수 있습니다.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"123456"}'

코드를 확인한 후, 이제 인증 기록 ID를 사용하여 사용자의 식별자를 업데이트할 수 있습니다.

인증에 대해 더 알고 싶다면 Account API에 의한 보안 인증을 참조하세요.

인증 기록 ID를 포함하여 요청 보내기

사용자의 식별자를 업데이트하기 위한 요청을 보낼 때, 요청 헤더의 logto-verification-id 필드에 인증 기록 ID를 포함해야 합니다.

사용자의 비밀번호 업데이트

사용자의 비밀번호를 업데이트하려면 POST /api/my-account/password 엔드포인트를 사용할 수 있습니다.

curl -X POST https://[tenant-id].logto.app/api/my-account/password \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"password":"..."}'

팁:

가입 시 생성된 비밀번호와 마찬가지로, Account API를 통해 설정된 비밀번호는 콘솔 > 보안 > 비밀번호 정책에서 구성한 비밀번호 정책을 준수해야 합니다. Logto는 비밀번호가 정책을 통과하지 못하면 상세한 검증 결과와 오류 메시지를 반환합니다.

새 이메일 업데이트 또는 연결

노트:

이 방법을 사용하려면 이메일 커넥터를 구성하고, BindNewIdentifier 템플릿이 구성되어 있는지 확인해야 합니다.

새 이메일을 업데이트하거나 연결하려면, 먼저 이메일 소유권을 증명해야 합니다.

POST /api/verifications/verification-code 엔드포인트를 호출하여 인증 코드를 요청하세요.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."}}'

응답에서 verificationId를 찾을 수 있으며, 이메일로 인증 코드를 받게 됩니다. 이를 사용하여 이메일을 인증하세요.

curl -X POST https://[tenant-id].logto.app/api/verifications/verification-code/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"identifier":{"type":"email","value":"..."},"verificationId":"...","code":"..."}'

코드를 확인한 후, 이제 PATCH /api/my-account/primary-email를 호출하여 사용자의 이메일을 업데이트할 수 있으며, verificationId를 요청 본문에 newIdentifierVerificationRecordId로 설정하세요.

두 개의 다른 인증 기록 ID:

이 요청에는 두 개의 별도 인증 기록 ID가 필요합니다:

logto-verification-id (헤더): 민감한 변경을 하기 전에 사용자의 아이덴티티를 증명합니다. 사용자의 비밀번호를 확인하거나 사용자의 기존 이메일 또는 전화로 인증 코드를 보내 얻을 수 있습니다.
newIdentifierVerificationRecordId (본문): 새 이메일 주소의 소유권을 증명합니다. 이는 위의 POST /api/verifications/verification-code 호출에서 반환된 verificationRecordId입니다.

curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  # 사용자 아이덴티티 확인 (비밀번호 또는 기존 이메일/전화 인증에서)
  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # "newIdentifierVerificationRecordId"는 새 이메일의 소유권을 증명합니다 (위의 인증 코드 흐름에서)
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"<verification_record_id_from_new_email>"}'

팁:

가입 시 수집된 이메일과 마찬가지로, Account API를 통해 연결된 모든 이메일은 콘솔 > 보안 > 차단 목록에서 구성한 차단 목록 검증을 통과해야 합니다. 이메일이 정책을 위반하면 Logto는 요청을 거부하고 상세한 오류를 반환합니다.

사용자의 이메일 제거

사용자의 이메일을 제거하려면 DELETE /api/my-account/primary-email 엔드포인트를 사용할 수 있습니다.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

전화 관리

노트:

이 방법을 사용하려면 SMS 커넥터를 구성하고, BindNewIdentifier 템플릿이 구성되어 있는지 확인해야 합니다.

이메일 업데이트와 유사하게, PATCH /api/my-account/primary-phone 엔드포인트를 사용하여 새 전화를 업데이트하거나 연결할 수 있습니다. 그리고 DELETE /api/my-account/primary-phone 엔드포인트를 사용하여 사용자의 전화를 제거할 수 있습니다.

새 소셜 연결을 추가하려면, 먼저 POST /api/verifications/social 엔드포인트를 사용하여 인가 URL을 요청해야 합니다.

curl -X POST https://[tenant-id].logto.app/api/verifications/social \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorId":"...","redirectUri":"...","state":"..."}'

connectorId: 소셜 커넥터의 ID.
redirectUri: 사용자가 애플리케이션을 인가한 후 리디렉션되는 URI로, 이 URL에 웹 페이지를 호스팅하고 콜백을 캡처해야 합니다.
state: 사용자가 애플리케이션을 인가한 후 반환되는 상태로, CSRF 공격을 방지하기 위해 사용되는 임의의 문자열입니다.

응답에서 verificationRecordId를 찾을 수 있으며, 나중에 사용할 수 있도록 보관하세요.

사용자가 애플리케이션을 인가한 후, redirectUri에서 state 매개변수와 함께 콜백을 받게 됩니다. 그런 다음 POST /api/verifications/social/verify 엔드포인트를 사용하여 소셜 연결을 확인할 수 있습니다.

curl -X POST https://[tenant-id].logto.app/api/verifications/social/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"connectorData":"...","verificationRecordId":"..."}'

connectorData는 사용자가 애플리케이션을 인가한 후 소셜 커넥터에서 반환된 데이터로, 콜백 페이지에서 redirectUri의 쿼리 매개변수를 구문 분석하여 connectorData 필드의 값으로 JSON으로 래핑해야 합니다.

마지막으로, POST /api/my-account/identities 엔드포인트를 사용하여 소셜 연결을 추가할 수 있습니다.

두 개의 다른 인증 기록 ID:

이 요청에는 두 개의 별도 인증 기록 ID가 필요합니다:

logto-verification-id (헤더): 민감한 변경을 하기 전에 사용자의 아이덴티티를 증명합니다. 사용자의 비밀번호를 확인하거나 사용자의 기존 이메일 또는 전화로 인증 코드를 보내 얻을 수 있습니다.
newIdentifierVerificationRecordId (본문): 연결 중인 소셜 아이덴티티를 식별합니다. 이는 위의 POST /api/verifications/social 호출에서 반환된 verificationRecordId입니다.

curl -X POST https://[tenant-id].logto.app/api/my-account/identities \
  -H 'authorization: Bearer <access_token>' \
  # 사용자 아이덴티티 확인 (비밀번호 또는 기존 이메일/전화 인증에서)
  -H 'logto-verification-id: <verification_record_id_from_existing_identifier>' \
  -H 'content-type: application/json' \
  # "newIdentifierVerificationRecordId"는 연결할 소셜 연결을 식별합니다 (위의 소셜 인증 흐름에서)
  --data-raw '{"newIdentifierVerificationRecordId":"<verification_record_id_from_social>"}'

소셜 연결을 제거하려면 DELETE /api/my-account/identities 엔드포인트를 사용할 수 있습니다.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/identities/[connector_target_id] \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

새 WebAuthn 패스키 연결

노트:

먼저 MFA 및 WebAuthn을 활성화하세요.

노트:

이 방법을 사용하려면 계정 센터 설정에서 mfa 필드를 활성화해야 합니다.

1단계: 프론트엔드 앱 출처를 관련 출처에 추가

WebAuthn 패스키는 **Relying Party ID (RP ID)**라는 특정 호스트 이름에 바인딩됩니다. RP ID의 출처에 호스팅된 애플리케이션만 해당 패스키로 등록하거나 인증할 수 있습니다.

프론트엔드 애플리케이션이 Logto의 인증 페이지와 다른 도메인에서 Account API를 호출하므로, 교차 출처 패스키 작업을 허용하려면 관련 출처를 구성해야 합니다.

Logto가 RP ID를 결정하는 방법:

기본 설정: Logto의 기본 도메인 https://[tenant-id].logto.app만 사용하는 경우, RP ID는 [tenant-id].logto.app입니다.
사용자 정의 도메인: 사용자 정의 도메인을 https://auth.example.com과 같이 구성한 경우, RP ID는 auth.example.com이 됩니다.

관련 출처 구성:

PATCH /api/account-center 엔드포인트를 사용하여 프론트엔드 애플리케이션의 출처를 추가하세요. 예를 들어, 앱의 계정 센터가 https://account.example.com에서 실행되는 경우:

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"webauthnRelatedOrigins":["https://account.example.com"]}'

노트:

WebAuthn은 관련 출처에 대해 최대 5개의 고유한 eTLD+1 레이블을 지원합니다. eTLD+1 (효과적인 최상위 도메인 플러스 한 레이블)은 등록 가능한 도메인 부분입니다. 예를 들어:

https://example.com, https://app.example.com, https://auth.example.com은 하나의 레이블 (example.com)로 간주됩니다.
https://shopping.com, https://shopping.co.uk, https://shopping.co.jp도 하나의 레이블 (shopping)로 간주됩니다.
https://example.com과 https://another.com은 두 개의 레이블로 간주됩니다.

관련 출처로 5개 이상의 다른 도메인을 지원해야 하는 경우, 관련 출처 요청 문서를 참조하세요.

2단계: 새 등록 옵션 요청

POST /api/verifications/web-authn/registration 엔드포인트를 사용하여 새 패스키 등록을 요청하세요. Logto는 각 사용자 계정이 여러 패스키를 등록할 수 있도록 허용합니다.

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

응답은 다음과 같습니다:

{
  "registrationOptions": "...",
  "verificationRecordId": "...",
  "expiresAt": "..."
}

3단계: 로컬 브라우저에서 패스키 등록

@simplewebauthn/browser를 예로 들어, startRegistration 함수를 사용하여 로컬 브라우저에서 패스키를 등록할 수 있습니다.

import { startRegistration } from '@simplewebauthn/browser';

// ...
const response = await startRegistration({
  optionsJSON: registrationOptions, // 1단계에서 서버에서 반환된 데이터
});
// 나중에 사용할 수 있도록 응답을 저장하세요

4단계: 패스키 등록 확인

POST /api/verifications/web-authn/registration/verify 엔드포인트를 사용하여 패스키 등록을 확인하세요.

이 단계는 인증자가 생성한 암호화 서명을 확인하여 패스키가 합법적으로 생성되었으며 전송 중에 변조되지 않았음을 보장합니다.

curl -X POST https://[tenant-id].logto.app/api/verifications/web-authn/registration/verify \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --data-raw '{"payload":"...","verificationRecordId":"..."}'

payload: 2단계에서 로컬 브라우저의 응답.
verificationRecordId: 1단계에서 서버에서 반환된 인증 기록 ID.

5단계: 패스키 연결

마지막으로, POST /api/my-account/mfa-verifications 엔드포인트를 사용하여 패스키를 사용자의 계정에 연결할 수 있습니다.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}'

verification_record_id: 사용자의 기존 요소를 확인하여 부여된 유효한 인증 기록 ID입니다. 자세한 내용은 인증 기록 ID 얻기 섹션을 참조하세요.
type: MFA 요소의 유형으로, 현재는 WebAuthn만 지원됩니다.
newIdentifierVerificationRecordId: 1단계에서 서버에서 반환된 인증 기록 ID.

기존 WebAuthn 패스키 관리

기존 WebAuthn 패스키를 관리하려면 GET /api/my-account/mfa-verifications 엔드포인트를 사용하여 현재 패스키 및 기타 MFA 인증 요소를 가져올 수 있습니다.

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>'

응답 본문은 다음과 같습니다:

[
  {
    "id": "...",
    "type": "WebAuthn",
    "name": "...",
    "agent": "...",
    "createdAt": "...",
    "updatedAt": "..."
  }
]

id: 인증의 ID.
type: 인증의 유형, WebAuthn 패스키의 경우 WebAuthn.
name: 패스키의 이름, 선택적 필드.
agent: 패스키의 사용자 에이전트.

PATCH /api/my-account/mfa-verifications/{verificationId}/name 엔드포인트를 사용하여 패스키 이름을 업데이트하세요:

curl -X PATCH https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId}/name \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"name":"..."}'

DELETE /api/my-account/mfa-verifications/{verificationId} 엔드포인트를 사용하여 패스키를 삭제하세요:

curl -X DELETE https://[tenant-id].logto.app/api/my-account/mfa-verifications/{verificationId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>'

새 TOTP 연결

노트:

먼저 MFA 및 TOTP를 활성화하세요.

노트:

이 방법을 사용하려면 계정 센터 설정에서 mfa 필드를 활성화해야 합니다.

1단계: TOTP 비밀 생성

POST /api/my-account/mfa-verifications/totp-secret/generate 엔드포인트를 사용하여 TOTP 비밀을 생성하세요.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/totp-secret/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

응답 본문은 다음과 같습니다:

{
  "secret": "..."
}

2단계: 사용자에게 TOTP 비밀 표시

비밀을 사용하여 QR 코드를 생성하거나 사용자에게 직접 표시하세요. 사용자는 이를 인증 앱 (예: Google Authenticator, Microsoft Authenticator, Authy)에 추가해야 합니다.

QR 코드의 URI 형식은 다음과 같아야 합니다:

otpauth://totp/[Issuer]:[Account]?secret=[Secret]&issuer=[Issuer]

예시:

otpauth://totp/YourApp:user@example.com?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

3단계: TOTP 요소 바인딩

사용자가 비밀을 인증 앱에 추가한 후, 이를 확인하고 계정에 바인딩해야 합니다. POST /api/my-account/mfa-verifications 엔드포인트를 사용하여 TOTP 요소를 바인딩하세요.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"Totp","secret":"..."}'

verification_record_id: 사용자의 기존 요소를 확인하여 부여된 유효한 인증 기록 ID입니다. 자세한 내용은 인증 기록 ID 얻기 섹션을 참조하세요.
type: Totp여야 합니다.
secret: 1단계에서 생성된 TOTP 비밀.

노트:

사용자는 한 번에 하나의 TOTP 요소만 가질 수 있습니다. 사용자가 이미 TOTP 요소를 가지고 있는 경우, 다른 요소를 추가하려고 하면 422 오류가 발생합니다.

백업 코드 관리

노트:

먼저 MFA 및 백업 코드를 활성화하세요.

노트:

이 방법을 사용하려면 계정 센터 설정에서 mfa 필드를 활성화해야 합니다.

1단계: 새 백업 코드 생성

POST /api/my-account/mfa-verifications/backup-codes/generate 엔드포인트를 사용하여 10개의 새 백업 코드를 생성하세요.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes/generate \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json'

응답 본문은 다음과 같습니다:

{
  "codes": ["...", "...", "..."]
}

2단계: 사용자에게 백업 코드 표시

백업 코드를 사용자의 계정에 바인딩하기 전에, 사용자에게 이를 표시하고 다음을 지시해야 합니다:

즉시 이 코드를 다운로드하거나 기록하세요
안전한 장소에 보관하세요
각 코드는 한 번만 사용할 수 있음을 이해하세요
이러한 코드는 기본 MFA 방법에 접근할 수 없을 때 최후의 수단임을 알아두세요

코드를 명확하고 쉽게 복사할 수 있는 형식으로 표시하고 다운로드 옵션 (예: 텍스트 파일 또는 PDF로)을 제공하는 것을 고려하세요.

3단계: 사용자 계정에 백업 코드 바인딩

POST /api/my-account/mfa-verifications 엔드포인트를 사용하여 백업 코드를 사용자 계정에 바인딩하세요.

curl -X POST https://[tenant-id].logto.app/api/my-account/mfa-verifications \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json' \
  --data-raw '{"type":"BackupCode","codes":["...","...","..."]}'

verification_record_id: 사용자의 기존 요소를 확인하여 부여된 유효한 인증 기록 ID입니다. 자세한 내용은 인증 기록 ID 얻기 섹션을 참조하세요.
type: BackupCode여야 합니다.
codes: 이전 단계에서 생성된 백업 코드 배열.

노트:

사용자는 한 번에 하나의 백업 코드 세트만 가질 수 있습니다. 모든 코드가 사용된 경우, 사용자는 새 코드를 생성하고 바인딩해야 합니다.
백업 코드는 유일한 MFA 요소가 될 수 없습니다. 사용자는 최소한 하나 이상의 다른 MFA 요소 (예: WebAuthn 또는 TOTP)를 활성화해야 합니다.
각 백업 코드는 한 번만 사용할 수 있습니다.

기존 백업 코드 보기

기존 백업 코드와 사용 상태를 보려면 GET /api/my-account/mfa-verifications/backup-codes 엔드포인트를 사용하세요:

curl https://[tenant-id].logto.app/api/my-account/mfa-verifications/backup-codes \
  -H 'authorization: Bearer <access_token>'

응답 본문은 다음과 같습니다:

{
  "codes": [
    {
      "code": "...",
      "usedAt": null
    },
    {
      "code": "...",
      "usedAt": "2024-01-15T10:30:00.000Z"
    }
  ]
}

code: 백업 코드.
usedAt: 코드가 사용된 타임스탬프, 아직 사용되지 않은 경우 null.

사용자 세션 관리

활성 세션 목록

사용자의 활성 세션을 나열하려면 GET /api/my-account/sessions 엔드포인트를 사용할 수 있습니다.

노트:

이 엔드포인트에 접근하려면 UserScope.Sessions 스코프가 필요합니다.
계정 센터 설정에서 Sessions 필드는 ReadOnly 또는 Edit으로 설정되어야 합니다.

curl https://[tenant-id].logto.app/api/my-account/sessions \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

세션 ID로 세션 취소

특정 세션을 취소하려면 DELETE /api/my-account/sessions/{sessionId} 엔드포인트를 사용하세요.

노트:

이 엔드포인트에 접근하려면 UserScope.Sessions 스코프가 필요합니다.
계정 센터 설정에서 Sessions 필드는 Edit으로 설정되어야 합니다.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/sessions/{sessionId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

선택적 쿼리 매개변수:

revokeGrantsTarget: 세션과 함께 취소할 권한의 대상을 선택적으로 지정합니다. 가능한 값:
- all: 세션과 관련된 모든 권한을 취소합니다.
- firstParty: 세션과 관련된 1차 앱 권한만 취소합니다. (대부분의 사용 사례에 권장되며, 사용자의 앱에 대한 접근을 취소하면서 타사 앱 권한은 유지하여 더 나은 사용자 경험을 제공합니다.)
- 지정되지 않음: 기본 동작은 offline_access 스코프가 없는 권한을 취소하며, 이는 일반적으로 세션에 대한 리프레시 토큰이 아닌 권한을 취소하는 것을 의미합니다.

사용자 승인 앱 (권한) 관리

사용자가 계정 설정 페이지에서 승인된 앱을 검토하고 취소해야 할 때 사용자 승인 앱 (권한) API를 사용하세요.

노트:

앱 권한 API는 세션 API와 동일한 권한 모델을 공유합니다.
UserScope.Sessions 스코프가 필요합니다.
계정 센터 설정에서 Sessions 필드가 활성화되어야 합니다:
- 권한을 나열하려면 ReadOnly 또는 Edit.
- 권한을 취소하려면 Edit.

활성 앱 권한 목록

현재 사용자의 활성 앱 권한을 나열하려면 GET /api/my-account/grants 엔드포인트를 사용하세요.

curl https://[tenant-id].logto.app/api/my-account/grants \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

선택적 쿼리 매개변수:

appType=firstParty: 1차 앱 권한만 반환합니다.
appType=thirdParty: 타사 앱 권한만 반환합니다.
appType 생략: 모든 활성 권한을 반환합니다.

curl "https://[tenant-id].logto.app/api/my-account/grants?appType=thirdParty" \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

권한 ID로 앱 권한 취소

특정 앱 권한을 취소하려면 DELETE /api/my-account/grants/{grantId} 엔드포인트를 사용하세요.

curl -X DELETE https://[tenant-id].logto.app/api/my-account/grants/{grantId} \
  -H 'authorization: Bearer <access_token>' \
  -H 'logto-verification-id: <verification_record_id>' \
  -H 'content-type: application/json'

권한이 취소되면, 해당 권한에 대해 이전에 발급된 불투명 액세스 토큰 및 리프레시 토큰이 무효화됩니다.

Logto Account API란 무엇인가요​

Account API 활성화 방법​

Account API 접근 방법​

액세스 토큰 가져오기​

액세스 토큰을 사용하여 Account API 접근​

기본 계정 정보 관리​

사용자 계정 정보 조회​

기본 계정 정보 업데이트​

식별자 및 기타 민감한 정보 관리​

인증 기록 ID 얻기​

사용자의 비밀번호 확인​

사용자의 이메일 또는 전화로 인증 코드 보내기​

인증 기록 ID를 포함하여 요청 보내기​

사용자의 비밀번호 업데이트​

새 이메일 업데이트 또는 연결​

사용자의 이메일 제거​

전화 관리​

새 소셜 연결 추가​

소셜 연결 제거​

새 WebAuthn 패스키 연결​

기존 WebAuthn 패스키 관리​

새 TOTP 연결​

백업 코드 관리​

사용자 세션 관리​

사용자 승인 앱 (권한) 관리​

Logto Account API란 무엇인가요

Account API 활성화 방법

Account API 접근 방법

액세스 토큰 가져오기

액세스 토큰을 사용하여 Account API 접근

기본 계정 정보 관리

사용자 계정 정보 조회

기본 계정 정보 업데이트

식별자 및 기타 민감한 정보 관리

인증 기록 ID 얻기

사용자의 비밀번호 확인

사용자의 이메일 또는 전화로 인증 코드 보내기

인증 기록 ID를 포함하여 요청 보내기

사용자의 비밀번호 업데이트

새 이메일 업데이트 또는 연결

사용자의 이메일 제거

전화 관리

새 소셜 연결 추가

소셜 연결 제거

새 WebAuthn 패스키 연결

기존 WebAuthn 패스키 관리

새 TOTP 연결

백업 코드 관리

사용자 세션 관리

사용자 승인 앱 (권한) 관리