본문으로 건너뛰기

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> 형식으로 첨부하세요.
노트:

액세스 토큰 (Access token)에 적절한 권한이 부여되도록 Logto 설정에서 해당 스코프 (Scope)를 올바르게 구성해야 합니다.

예를 들어, POST /api/my-account/primary-email API를 사용하려면 email 스코프 (Scope)를, POST /api/my-account/primary-phone API를 사용하려면 phone 스코프 (Scope)를 구성해야 합니다.

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

const config: LogtoConfig = {
  // ...other options
  // 사용 사례에 맞는 적절한 스코프 (Scope)를 추가하세요.
  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 접근 방법​

액세스 토큰 (Access token) 가져오기​

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

공식 SDK를 사용하지 않는 경우, 액세스 토큰 (Access token) 발급 요청 시 /oidc/token의 resource를 비워야 합니다.

액세스 토큰 (Access token)으로 Account API 접근하기​

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

사용자 계정 정보를 조회하는 예시:

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

기본 계정 정보 관리​

사용자 계정 정보 조회​

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

프로필을 업데이트하려면 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 얻기​

먼저 인증(Verification) 레코드 ID를 얻어야 합니다. 이는 식별자 업데이트 시 사용자의 신원을 검증하는 데 사용됩니다.

인증(Verification) 레코드 ID를 얻으려면 사용자의 비밀번호를 검증하거나, 이메일 또는 전화번호로 인증 코드를 전송할 수 있습니다.

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

사용자 비밀번호 검증​

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) 레코드 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":"..."}'

코드 검증이 완료되면, 이제 사용자의 이메일을 업데이트할 수 있습니다. 요청 본문에 newIdentifierVerificationRecordId로 verificationId를 설정하세요.

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 엔드포인트로 사용자의 전화번호를 삭제할 수 있습니다.

새 소셜 연결을 추가하려면 먼저 인가 (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: 사용자가 애플리케이션 인가 후 리디렉션될 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>'
노트:

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

노트:

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

0단계: 프론트엔드 앱 오리진을 관련 오리진에 추가하세요.

브라우저의 패스키는 특정 호스트네임(RP ID)에 연결되며, 해당 RP ID의 오리진에서만 패스키 등록 또는 검증이 가능합니다. 하지만 Account API에 요청을 보내는 프론트엔드 앱은 Logto의 로그인 페이지와 다르기 때문에, 프론트엔드 앱 오리진을 관련 오리진 목록에 추가해야 합니다. 이를 통해 프론트엔드 앱에서 다른 RP ID 하에서 패스키를 등록 및 검증할 수 있습니다.

기본적으로 Logto는 RP ID를 테넌트 도메인으로 설정합니다. 예를 들어, 테넌트 도메인이 https://example.logto.app라면 RP ID는 example.logto.app입니다. 커스텀 도메인을 사용하는 경우 RP ID는 해당 커스텀 도메인이 됩니다. 예: https://auth.example.com → auth.example.com.

이제 프론트엔드 앱 오리진이 https://account.example.com이라면, 관련 오리진에 추가하세요:

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

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

1단계: 신규 등록 옵션 요청

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": "..."
}

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

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

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

// ...
const response = await startRegistration({
  optionsJSON: registrationOptions, // 1단계에서 서버가 반환한 데이터
});
// 이후 사용을 위해 response를 저장하세요

3단계: 패스키 검증

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

4단계: 패스키 연결

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: 패스키의 사용자 에이전트

패스키 이름 업데이트:

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

패스키 삭제:

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>'
노트:

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

노트:

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

1단계: 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 요소 바인딩

사용자가 인증 앱에 시크릿을 추가한 후, 이를 검증하고 계정에 바인딩해야 합니다:

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단계: 새 백업 코드 생성

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단계: 사용자에게 백업 코드 표시

important:

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

  • 즉시 다운로드하거나 적어두기
  • 안전한 장소에 보관하기
  • 각 코드는 한 번만 사용할 수 있음
  • 기본 MFA 수단을 잃어버렸을 때 최후의 수단임을 인지하기

코드는 명확하고 복사하기 쉬운 형식으로 표시하고, 다운로드 옵션(예: 텍스트 파일, PDF 등)을 제공하는 것이 좋습니다.

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

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 등)를 활성화해야 합니다.
  • 각 백업 코드는 한 번만 사용할 수 있습니다.

기존 백업 코드 조회

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