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 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 활성화를 토글하여 켜세요.

활성화 후, 최근 인증 시간(1~120분, 기본값 10분)과 식별자, 프로필 데이터, 서드파티 토큰 접근에 대한 필드별 권한을 설정할 수 있습니다. 각 필드는 Off, ReadOnly, Edit 중 선택할 수 있으며, 기본값은 Off입니다.

1. 보안 필드:
   • 필드: 기본 이메일, 기본 전화번호, 소셜 아이덴티티, 비밀번호, 패스키, MFA, 개인 액세스 토큰 등
   • 민감한 작업은 1st-party 애플리케이션에서 최근 사용자 인증이 필요합니다. 즉, acr이 urn:logto:acr:1fa를 만족하고, 설정한 최근 인증 시간 내에 발급된 액세스 토큰이 필요합니다. (OIDC 단계 상승 인증 참고)
   • MFA용 WebAuthn 패스키를 사용하려면 프론트엔드 앱 도메인을 WebAuthn 관련 Origin에 추가해야 계정 센터와 로그인 경험에서 패스키를 공유할 수 있습니다. 새 WebAuthn 패스키 연결 참고
2. 프로필 필드:
   • 필드: 사용자명, 이름, 아바타, 프로필 (기타 표준 프로필 속성), 커스텀 데이터
   • 최종 사용자는 별도의 추가 인증 없이 수정할 수 있으나, username은 최근 사용자 인증이 추가로 필요합니다.
3. 비밀 금고:
   • OIDC 또는 OAuth 소셜/엔터프라이즈 커넥터의 경우, Logto 비밀 금고가 인증 후 서드파티 액세스 토큰 및 리프레시 토큰을 안전하게 저장합니다. 앱은 사용자가 다시 로그인하지 않아도 외부 API(예: Google Calendar 동기화 등)를 호출할 수 있습니다. Account API 활성화 시 토큰 조회가 자동으로 가능해집니다.
4. 세션 관리:
   • 활성화 시 사용자는 자신의 활성 세션(디바이스 정보, 마지막 로그인 시간 포함)을 조회 및 관리할 수 있습니다. 특정 디바이스에서 로그아웃(세션 해제)도 가능합니다.
   • 동일한 Sessions 필드 권한이 사용자 승인 앱(그랜트) 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, // 사용자 프로필 관리용
    UserScope.Sessions, // 사용자 세션 및 앱 그랜트 관리용
  ],
};

액세스 토큰 가져오기

애플리케이션에 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 작업은 1st-party 애플리케이션에서 최근 사용자 인증이 필요합니다. 즉, 액세스 토큰에 acr이 urn:logto:acr:1fa를 만족하고, auth_time이 테넌트의 최근 인증 윈도우(기본 600초 / 10분, 60~7,200초까지 설정 가능) 내에 있어야 합니다.

액세스 토큰에 urn:logto:acr:1fa가 없거나 윈도우를 초과한 경우, Account API는 RFC 9470의 WWW-Authenticate 헤더와 함께 401 Unauthorized를 반환합니다 (error="insufficient_user_authentication", acr_values="urn:logto:acr:1fa", max_age="<window>"). 해당 파라미터로 OIDC 단계 상승 인증 요청을 시작하고, 새로 발급받은 액세스 토큰으로 다시 호출하세요.

노트:

새로운 이메일, 전화번호, 소셜 아이덴티티, WebAuthn 패스키를 바인딩할 때는 Verification API를 통해 해당 식별자/요소의 소유권을 증명하고, 요청 본문에 newIdentifierVerificationRecordId를 전달해야 합니다. 각 섹션의 예시를 참고하세요.

사용자 비밀번호 업데이트

사용자 비밀번호를 업데이트하려면 POST /api/my-account/password 엔드포인트를 사용하세요.

curl -X POST https://[tenant-id].logto.app/api/my-account/password \
  -H 'authorization: Bearer <access_token>' \
  -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로 전달하세요.

curl -X POST https://[tenant-id].logto.app/api/my-account/primary-email \
  -H 'authorization: Bearer <access_token>' \
  -H 'content-type: application/json' \
  --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>'

전화번호 관리

노트:

이 방법을 사용하려면 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 'content-type: application/json' \
  --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>'

새 WebAuthn 패스키 연결

노트:

먼저 MFA 및 WebAuthn 활성화를 잊지 마세요.

노트:

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

1단계: 프론트엔드 앱 Origin을 관련 Origin에 추가

WebAuthn 패스키는 **Relying Party ID (RP ID)**라는 특정 호스트네임에 바인딩됩니다. 해당 Origin에서만 패스키 등록/인증이 가능합니다.

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

Logto의 RP ID 결정 방식:

• 기본 도메인 사용 시: 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"]}'

노트:

WebAuthn은 Related Origins로 최대 5개의 고유 eTLD+1 레이블을 지원합니다. eTLD+1(유효 최상위 도메인+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개를 초과하는 도메인을 지원해야 한다면 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 'content-type: application/json' \
  --data-raw '{"type":"WebAuthn","newIdentifierVerificationRecordId":"..."}'

• 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 '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>'

새 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:[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 'content-type: application/json' \
  --data-raw '{"type":"Totp","secret":"..."}'

• type: 반드시 Totp
• secret: 1단계에서 생성한 TOTP 시크릿

노트:

사용자는 한 번에 하나의 TOTP 요소만 가질 수 있습니다. 이미 TOTP 요소가 있으면 추가 시 422 오류가 발생합니다.

기존 TOTP 교체

사용자가 이미 TOTP 요소를 설정한 경우, PUT /api/my-account/mfa-verifications/totp 엔드포인트로 새 요소로 교체할 수 있습니다. 이 작업은 멱등적이며 기존 TOTP를 제거하고 새 요소를 바인딩합니다.

노트:

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

1단계: 새 TOTP 시크릿 생성

POST /api/my-account/mfa-verifications/totp-secret/generate 엔드포인트로 새 TOTP 시크릿을 생성하고, 새 TOTP 연결과 동일하게 사용자에게 표시하세요.

2단계: TOTP 요소 교체

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

• secret: 1단계에서 생성한 새 TOTP 시크릿
• code: 새 시크릿에서 생성된 TOTP 코드(바인딩 확인용)

백업 코드 관리

노트:

먼저 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 'content-type: application/json' \
  --data-raw '{"type":"BackupCode","codes":["...","...","..."]}'

• 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

2단계 인증 설정 관리

노트:

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

최종 사용자는 자신의 계정에 대해 2단계 인증을 켜거나 끌 수 있습니다. 예를 들어, 사용자가 MFA 요소(패스키 등)를 설정했지만 로그인 시 추가 인증 없이 사용하고 싶을 때 — 2단계 인증을 비활성화하면 로그인 시 MFA 프롬프트를 건너뛰고 MFA 요소는 그대로 유지할 수 있습니다. 이는 사용자별 skipMfaOnSignIn 설정으로 제어됩니다.

현재 MFA 설정 조회

GET /api/my-account/mfa-settings 엔드포인트로 사용자의 현재 2단계 인증 설정을 조회할 수 있습니다.

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

응답 예시:

{
  "skipMfaOnSignIn": false
}

MFA 설정 업데이트

2단계 인증을 활성화/비활성화하려면 PATCH /api/my-account/mfa-settings 엔드포인트를 사용하세요.

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

• skipMfaOnSignIn: 사용자의 2단계 인증을 비활성화하려면 true, 활성화하려면 false로 설정

노트:

이 설정은 MFA 정책이 **선택적(Optional)**일 때만 적용됩니다. MFA가 필수(Mandatory) 또는 **적응형(Adaptive)**인 경우 skipMfaOnSignIn 설정은 무시되고 MFA가 강제 적용됩니다.

사용자 세션 관리

활성 세션 목록 조회

사용자의 활성 세션을 조회하려면 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 '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 'content-type: application/json'

선택적 쿼리 파라미터:

• revokeGrantsTarget: 세션과 함께 해제할 그랜트의 대상을 지정할 수 있습니다. 가능한 값:
  • all: 세션과 연관된 모든 그랜트 해제
  • firstParty: 세션과 연관된 1st-party 앱 그랜트만 해제(대부분의 경우 권장, 3rd-party 앱 그랜트는 유지되어 더 나은 사용자 경험 제공)
  • 미지정: 기본 동작은 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 'content-type: application/json'

선택적 쿼리 파라미터:

• appType=firstParty: 1st-party 앱 그랜트만 반환
• appType=thirdParty: 3rd-party 앱 그랜트만 반환
• appType 미지정: 모든 활성 그랜트 반환

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

그랜트가 해제되면, 해당 그랜트로 발급된 불투명 액세스 토큰 및 리프레시 토큰은 모두 무효화됩니다.