Account API로 계정 설정하기

Logto Account API란?

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

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

노트:

액세스 토큰이 적절한 권한을 갖도록 하려면 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 = {
  // ...기타 옵션
  // 사용 사례에 맞는 적절한 스코프를 추가하세요.
  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, // 사용자 프로필 관리용
  ],
};

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

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

사용자 프로필 조회
사용자 프로필 업데이트
사용자 비밀번호 변경
이메일, 전화번호, 소셜 연결 등 사용자 아이덴티티 업데이트
MFA 요소(인증) 관리

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

노트:

다음 설정을 위한 전용 Account API는 곧 제공될 예정입니다: SSO, 사용자 정의 데이터, 계정 삭제. 그동안에는 Logto Management API를 사용하여 해당 기능을 구현할 수 있습니다. 자세한 내용은 Management API로 계정 설정하기를 참고하세요.

MFA 관리 API(TOTP 및 백업 코드)는 현재 개발 중이며 isDevFeaturesEnabled 플래그가 true로 설정된 경우에만 사용할 수 있습니다. WebAuthn 패스키 관리는 완전히 지원됩니다.

Account API 활성화 방법

기본적으로 Account API는 비활성화되어 있습니다. 활성화하려면 Management API를 사용하여 글로벌 설정을 업데이트해야 합니다.

API 엔드포인트 /api/account-center를 사용하여 계정 센터 설정을 조회 및 업데이트할 수 있습니다. 이를 통해 Account API를 활성화/비활성화하고 필드를 맞춤 설정할 수 있습니다.

예시 요청:

curl -X PATCH https://[tenant-id].logto.app/api/account-center \
  -H 'authorization: Bearer <access_token for Logto Management API>' \
  -H 'content-type: application/json' \
  --data-raw '{"enabled":true,"fields":{"username":"Edit"}}'

enabled 필드는 Account API의 활성화/비활성화를, fields 필드는 각 필드의 상태를 맞춤 설정합니다. 값은 Off, Edit, ReadOnly 중 하나가 될 수 있으며, 기본값은 Off입니다. 필드 목록:

name: 이름 필드
avatar: 아바타 필드
profile: 프로필 필드(하위 필드 포함)
username: 사용자명 필드
email: 이메일 필드
phone: 전화번호 필드
password: 비밀번호 필드(조회 시, 비밀번호가 설정되어 있으면 true, 아니면 false 반환)
social: 소셜 연결
mfa: MFA 요소

API 세부 정보는 Logto Management API Reference에서 확인하세요.

Account API 접근 방법

액세스 토큰 가져오기

애플리케이션에 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": "..."
}

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

기본 계정 정보 업데이트

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

username, name, avatar, customData를 업데이트하려면 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는 식별자 및 기타 민감 정보와 관련된 작업에 대해 추가 인가 (Authorization) 계층을 요구합니다.

인증(Verification) 기록 ID 얻기

먼저, 만료 시간 10분(TTL)이 있는 인증(Verification) 기록 ID를 받아야 합니다. 이는 민감 정보 업데이트 전에 사용자의 신원을 확인하는 데 사용됩니다. 즉, 사용자가 비밀번호, 이메일 인증 코드, SMS 인증 코드 등으로 신원을 성공적으로 인증하면 10분 동안 인증 관련 데이터(식별자, 자격 증명, 소셜 계정 연결, MFA 등)를 업데이트할 수 있습니다.

인증(Verification) 기록 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 템플릿이 설정되어 있어야 합니다.

이메일을 예로 들어, 새 인증 코드를 요청하고 인증(Verification) 기록 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": "..."
}

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

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"}'

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

인증(Verification)에 대해 더 알아보려면 Account API로 보안 인증을 참고하세요.

인증(Verification) 기록 ID와 함께 요청 보내기

사용자 식별자를 업데이트하는 요청을 보낼 때, 요청 헤더의 logto-verification-id 필드에 인증(Verification) 기록 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":"..."}'

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

노트:

이 방법을 사용하려면 이메일 커넥터를 구성하고, 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로 설정하세요.

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>' \
  -H 'content-type: application/json' \
  --data-raw '{"email":"...","newIdentifierVerificationRecordId":"..."}'

사용자 이메일 삭제

사용자 이메일을 삭제하려면 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로 인가(Authorization) 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: 사용자가 애플리케이션을 인가(Authorization)한 후 리디렉션될 URI. 이 URL에 웹 페이지를 호스팅하고 콜백을 수신해야 합니다.
state: 사용자가 애플리케이션을 인가(Authorization)한 후 반환될 상태. CSRF 공격 방지를 위한 임의 문자열입니다.

응답에서 verificationRecordId를 확인하고, 이후에 사용할 수 있도록 저장하세요.

사용자가 애플리케이션을 인가(Authorization)하면, 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는 사용자가 애플리케이션을 인가(Authorization)한 후 소셜 커넥터에서 반환된 데이터입니다. 콜백 페이지에서 redirectUri의 쿼리 파라미터를 파싱하여 JSON으로 감싸 connectorData 필드 값으로 전달해야 합니다.

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

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

소셜 연결을 삭제하려면 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를 호출하는 경우, Related Origins를 구성하여 교차 오리진 패스키 작업을 허용해야 합니다.

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

기본 설정: Logto의 기본 도메인 https://[tenant-id].logto.app만 사용하는 경우, RP ID는 [tenant-id].logto.app
커스텀 도메인: 커스텀 도메인 https://auth.example.com을 구성한 경우, RP ID는 auth.example.com

Related Origins 구성:

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"]}'

관련 오리진에 대해 더 알아보려면 Related Origin Requests 문서를 참고하세요.

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단계에서 서버가 반환한 데이터
});
// 이후 사용을 위해 response를 저장하세요

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단계에서 서버가 반환한 인증(Verification) 기록 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: 사용자의 기존 요소를 인증하여 부여받은 유효한 인증(Verification) 기록 ID. 자세한 내용은 인증(Verification) 기록 ID 얻기 섹션을 참고하세요.
type: MFA 요소 유형, 현재는 WebAuthn만 지원
newIdentifierVerificationRecordId: 1단계에서 서버가 반환한 인증(Verification) 기록 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/[발급자]:[계정]?secret=[시크릿]&issuer=[발급자]

예시:

otpauth://totp/YourApp:[email protected]?secret=JBSWY3DPEHPK3PXP&issuer=YourApp

3단계: TOTP 요소 바인딩

사용자가 인증 앱에 시크릿을 추가한 후, 이를 검증하고 계정에 바인딩해야 합니다. 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":"Totp","secret":"..."}'

verification_record_id: 사용자의 기존 요소를 인증하여 부여받은 유효한 인증(Verification) 기록 ID. 자세한 내용은 인증(Verification) 기록 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: 사용자의 기존 요소를 인증하여 부여받은 유효한 인증(Verification) 기록 ID. 자세한 내용은 인증(Verification) 기록 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

Logto Account API란?​

Account API 활성화 방법​

Account API 접근 방법​

액세스 토큰 가져오기​

액세스 토큰으로 Account API 접근하기​

기본 계정 정보 관리​

사용자 계정 정보 조회​

기본 계정 정보 업데이트​

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

인증(Verification) 기록 ID 얻기​

사용자 비밀번호 인증​

이메일 또는 전화번호로 인증 코드 전송하여 인증​

인증(Verification) 기록 ID와 함께 요청 보내기​

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

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

사용자 이메일 삭제​

전화번호 관리​

새 소셜 연결 추가​

소셜 연결 삭제​

새 WebAuthn 패스키 연결​

기존 WebAuthn 패스키 관리​

새 TOTP 연결​

백업 코드 관리​

Logto Account API란?

Account API 활성화 방법

Account API 접근 방법

액세스 토큰 가져오기

액세스 토큰으로 Account API 접근하기

기본 계정 정보 관리

사용자 계정 정보 조회

기본 계정 정보 업데이트

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

인증(Verification) 기록 ID 얻기

사용자 비밀번호 인증

이메일 또는 전화번호로 인증 코드 전송하여 인증

인증(Verification) 기록 ID와 함께 요청 보내기

사용자 비밀번호 업데이트

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

사용자 이메일 삭제

전화번호 관리

새 소셜 연결 추가

소셜 연결 삭제

새 WebAuthn 패스키 연결

기존 WebAuthn 패스키 관리

새 TOTP 연결

백업 코드 관리