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)을 얻고, 이를 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입니다.

1. 보안 필드:
   • 필드: 기본 이메일, 기본 전화번호, 소셜 아이덴티티, 비밀번호, MFA.
   • 최종 사용자가 이 필드를 수정하기 전, 비밀번호, 이메일 또는 SMS를 통해 본인 인증을 해야 하며, 10분 유효의 인증 기록 ID를 받아야 합니다. 인증 기록 ID 받기를 참고하세요.
   • MFA용 WebAuthn 패스키를 사용하려면, 프론트엔드 앱 도메인을 WebAuthn 관련 Origin에 추가하여 계정 센터와 로그인 경험이 패스키를 공유할 수 있도록 하세요. 새 WebAuthn 패스키 연결하기를 참고하세요.
2. 프로필 필드:
   • 필드: 사용자명, 이름, 아바타, 프로필 (기타 표준 프로필 속성), 커스텀 데이터.
   • 최종 사용자는 추가 인증 없이 이 필드를 수정할 수 있습니다.
3. 시크릿 볼트: OIDC 또는 OAuth 소셜 및 엔터프라이즈 커넥터의 경우, Logto 시크릿 볼트는 인증 후 서드파티 액세스 및 리프레시 토큰을 안전하게 저장합니다. 앱은 이후 외부 API(예: Google 캘린더 동기화 등)를 호출할 수 있으며, 사용자는 다시 로그인할 필요가 없습니다. Account API가 활성화되면 토큰 조회가 자동으로 가능해집니다.

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 = {
  // ...기타 옵션
  // 사용 사례에 맞는 적절한 스코프를 추가하세요.
  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, // 사용자 프로필 관리용
  ],
};

액세스 토큰 가져오기

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

공식 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) 계층을 요구합니다.

인증 기록 ID 받기

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

인증 기록 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":"..."}'

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

노트:

이 방법을 사용하려면 이메일 커넥터를 구성하고, 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로 인증 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의 쿼리 파라미터를 파싱하여 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단계: 프론트엔드 앱 Origin을 관련 Origin에 추가

WebAuthn 패스키는 **Relying Party ID (RP ID)**라 불리는 특정 호스트네임에 바인딩됩니다. 해당 Origin에서 호스팅되는 애플리케이션만 해당 패스키로 등록/인증할 수 있습니다.

프론트엔드 애플리케이션이 Logto 인증 페이지와 다른 도메인에서 Account API를 호출하는 경우, Related Origins를 구성하여 교차 Origin 패스키 작업을 허용해야 합니다.

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 엔드포인트로 프론트엔드 앱의 Origin을 추가하세요. 예를 들어, 앱의 계정 센터가 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"]}'

관련 Origin에 대해 더 알아보려면 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단계에서 서버가 반환한 인증 기록 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 엔드포인트를 사용하세요.

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입니다.