Account API로 계정 설정

Logto Account API란 무엇인가요

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

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

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 접근 방법

액세스 토큰 가져오기

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

기본 계정 정보 관리

사용자 계정 정보 조회

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 가져오기

먼저, 인증 기록 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 PATCH 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 PATCH 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 엔드포인트를 사용하여 사용자의 전화번호를 제거할 수 있습니다.

새로운 소셜 연결 추가

새로운 소셜 연결을 추가하려면 먼저 인가 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>'