Account API로 계정 설정 관리하기

Logto Account API란?

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

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

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

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

• 사용자 프로필 조회
• 사용자 프로필 업데이트
• 사용자 비밀번호 업데이트
• 이메일, 전화번호, 소셜 연결 등 사용자 아이덴티티 업데이트

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

노트:

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

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: 소셜 연결

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

Account API 접근 방법

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

애플리케이션에 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>'

기본 계정 정보 관리

사용자 계정 정보 조회

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) 절차가 필요합니다.

인증 기록 ID(verification record id) 얻기

먼저 인증 기록 ID를 얻어야 하며, 이는 식별자 업데이트 시 사용자의 신원을 확인하는 데 사용됩니다.

인증 기록 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를 사용하여 사용자의 식별자를 업데이트할 수 있습니다.

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

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

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

노트:

이 방법을 사용하려면 이메일 커넥터를 구성하고, 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":"..."}'

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

curl -X PATCH 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>'