사이드 메뉴
커뮤니케이션
API 제공
어드민 API
REST API
이 문서는 카카오 또는 공동체 서비스용 사용자 정보 REST API 사용법을 안내합니다.
사용자 정보 API는 로그인 및 연결된 상태의 사용자를 대상으로만 호출할 수 있으므로, 카카오 로그인을 연동한 서비스에서만 사용할 수 있습니다. 사용자의 앱 연결 여부에 따른 API 호출 제한 정보는 연결 상태와 지원 범위를 함께 참고합니다. 기본 정보 표에 필요한 권한이 기재돼 있는 API의 경우, 권한을 참고해 권한을 신청해야 사용할 수 있습니다.
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET / POST | 카카오http://kapi.kakao.com/v2/internal/user/me공동체 https://kapi.kakao.com/v2/internal/user/me외부 https://kapi.kakao.com/v2/user/me | 액세스 토큰 서비스 앱 어드민 키 위임 |
사용자의 카카오계정 정보를 받습니다. 내부 API는 응답에 사내 서비스에만 제공하는 추가 정보들을 포함합니다.
헤더에 원하는 인증 방식별 정보를 담아 GET으로 요청하고, 성공 시 사용자 정보가 담긴 JSON 객체를 받습니다. 특정 정보를 지정해 받으려면 property_keys 파라미터에 원하는 정보의 키의 목록을 아래와 같이 쉼표(,)로 구분해 전달합니다.
["id", "has_signed_up", "properties.${CUSTOM_PROPERTY_KEY}", "kakao_account.email"]
${SCOPE}_needs_agreement는 사용자로부터 추가 동의를 받으면 해당 동의항목의 값을 제공 받을 수 있는지 여부를 알려줍니다. needs_agreement를 참고합니다.- 사용자 프로퍼티인
properties는 앱 관리 페이지의 [카카오 로그인] > [고급] > [사용자 프로퍼티]에 설정된 키만 사용할 수 있습니다.
- 사용자가 수동 연결 API로 앱과 연결되기 전인 연결 대기(Preregistered) 상태일 경우, 가입에 필요한 최소한의 정보를 확인하기 위해 사용자 정보 조회 API를 호출할 수 있습니다. 사용자와 앱의 연결이 완료되어야 모든 사용자 정보를 제공 받을 수 있으며, 사용자의 연결 상태별 정보 제공 범위는 참고: 사용자 연결 상태에 따른 정보 제공 제한을 참고합니다.
- 모든 사용자 정보는 사용자가 동의해야만 제공 가능하고, 앱에 동의항목 설정이 필요합니다. 동의항목 설정은 동의항목을 참고합니다.
- 사용자 카카오계정과 앱의 연결 상태에 따라 일부 사용자 정보는 제공하지 않습니다. 사용자 상태별로 제공하는 응답 정보는 아래 표를 참고합니다.
- 각 사용자 정보의 사용자 동의 시 정보 제공 가능(
${SCOPE}_needs_agreement) 값은 연결 대기 사용자(PREREGISTERED) 또는 연결된 사용자(REGISTERED)만 보유 및 제공합니다. - 사용자와 앱의 연결 상태는 세 종류로 각각의 상태에 대한 설명은 연결 상태를 참고합니다.
| 사용자 정보 | 키(Key) | 연결되지 않은 사용자(NONE) | 연결 대기 사용자(PREREGISTERED) | 연결된 사용자(REGISTERED) |
|---|---|---|---|---|
| 회원번호 | id | O | O | O |
| 카카오계정 ID | account_id | O | O | |
| 다음 회원 ID | daum_user_id | O | O | |
| 카카오톡 회원번호 | talk_user_id | O | O | |
| 고유 ID | uuid | O | ||
| 프로필 정보(닉네임/프로필 사진) | profile | O | O | |
| 연결 여부 | has_signed_up | O | O | |
| 연결 시각 | connected_at | O | O | |
| 싱크 연결 시각 | synched_at | O | ||
| 사용자 프로퍼티 | properties | O | ||
| 카카오계정(이메일) | account_email | O | O | |
| 유효 이메일 여부 | is_email_valid | O | O | |
| 이메일 인증 여부 | is_email_verified | O | O | |
| 이름 | name | O | ||
| 성별 | gender | O | ||
| 연령대 | age_range | O | ||
| 출생연도 | birtyear | O | ||
| 생일 | birthday | O | ||
| 카카오계정(휴대전화번호) | phone_number | O | ||
| 카카오계정 가입일자 | account_creation_date | O | ||
| CI(연계정보) | ci | O | ||
| 본인인증 받은 시각 | ci_authenticated_at | O | ||
| 본인확인정보(이름) | legal_name | O | ||
| 본인확인정보(생년월일) | legal_birth_date | O | ||
| 본인확인정보(성별) | legal_gender | O | ||
| 본인확인정보(내외국인) | is_korean | O | ||
| 카카오톡 서비스 가입 여부 | is_kakaotalk_user | O | O | |
| 카카오계정 대표 정보 | display_id | O | ||
| 카카오계정 통합 여부 | unification_status | O | O | |
| 그룹 사용자 토큰 | group_user_token | O | O |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| secure_resource | Boolean | 이미지 URL 값의 HTTPS 반환 여부 (기본값: false) | X |
| property_keys | String[] | 응답에 포함할 정보의 키, 미지정 시 모든 정보 포함 키와 값의 형식으로 구성 (예: ["id","properties.${CUSTOM_PROPERTY_KEY}","kakao_account.email"]) | X |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_id | String | 사용자 정보를 가져올 사용자 ID | O |
| target_id_type | String | target_id 타입, 아래 중 하나
user_id만 사용 가능 | O |
| secure_resource | Boolean | 이미지 URL 값의 HTTPS 반환 여부 (기본값: false) | X |
| property_keys | String[] | 응답에 포함할 정보의 키, 미지정 시 모든 정보 포함 키와 값의 쌍으로 구성 (예: ["id","properties.${CUSTOM_PROPERTY_KEY}","kakao_account.email"]) | X |
- 내부 API 요청 시에만 사용 가능합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
- 요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키:
target_app_key,target_id,target_id_type - 서비스 앱 ID:
target_app_id,target_id,target_id_type - 액세스 토큰:
target_access_token
- 서비스 앱 키:
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_app_key | String | 사용자 정보를 가져올 서비스 앱의 키 | O(Optional) |
| target_app_id | Long | 사용자 정보를 가져올 서비스 앱의 ID | O(Optional) |
| target_access_token | String | 사용자 정보를 가져올 사용자의 액세스 토큰 값 | O(Optional) |
| target_id | String | 사용자 정보를 가져올 사용자 ID | O(Optional) |
| target_id_type | String | target_id 타입, 아래 중 하나
| O(Optional) |
| secure_resource | Boolean | 이미지 URL 값의 HTTPS 반환 여부 (기본값: false) | X |
| property_keys | String[] | 응답에 포함할 정보의 키, 미지정 시 모든 정보 포함 키와 값의 쌍으로 구성 (예: ["id","properties.${CUSTOM_PROPERTY_KEY}","kakao_account.email"]) | X |
- 요청 시
property_keys파라미터로 조회할 정보를 지정한 경우, 응답은 해당 값만 제공
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Long | 회원번호 | X |
| has_signed_up | Boolean | 자동 연결 설정을 비활성화한 경우만 존재 수동 연결 호출의 완료 여부 연결 대기(Preregistered) 상태일 때는 false연결(Registered) 상태일 때는 true | X |
| connected_at | Datetime | 서비스에 연결 완료된 시각, UTC (RFC3339 internet date/time 형식) | X |
| synched_at | Datetime | 카카오싱크 간편가입으로 로그인한 시각, UTC (RFC3339 internet date/time 형식) | X |
| group_user_token Permission | String | 그룹 앱 설정 권한 필요 해당 앱이 그룹 앱에 속한 경우 그룹에서 맵핑(Mapping) 정보로 사용할 수 있는 값 그룹 정보가 변경되면 바뀔 수 있는 값이므로 사용자 ID로 사용하지 말 것 | X |
| properties | JSON | 사용자 프로퍼티(Property) 설정하기 > 사용자 프로퍼티 참고 | X |
| kakao_account | KakaoAccount | 카카오계정 정보 | X |
| for_partner Permission | ForPartner | 카카오 및 공동체 앱에만 제공하는 추가 정보 | X |
has_${FIELD_NAME}: Deprecated, 각 사용자 정보 값 소유 여부(Boolean), 해당 사용자 정보의 제공 가능 여부를 확인하는 용도로 사용할 수 없음(참고: needs_agreement)
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| profile_nickname_needs_agreement | Boolean | 사용자 동의 시 닉네임 제공 가능 필요한 동의항목: 닉네임 | X |
| profile_image_needs_agreement | Boolean | 사용자 동의 시 프로필 사진 제공 가능 필요한 동의항목: 프로필 사진 | X |
| profile_needs_agreement | Boolean | 사용자 동의 시 프로필 정보(닉네임/프로필 사진) 제공 가능 필요한 동의항목: 프로필 정보(닉네임/프로필 사진) | X |
| profile | Profile | 프로필 정보 필요한 동의항목: 닉네임, 프로필 사진, 프로필 정보(닉네임/프로필 사진) | X |
| email_needs_agreement Permission | Boolean | 사용자 동의 시 카카오계정 대표 이메일 제공 가능 필요한 동의항목: 카카오계정(이메일) | X |
| is_email_valid Permission | Boolean | 이메일 유효 여부 유효한 이메일이라면 true(유효), 이메일이 다른 카카오계정에 사용돼 만료되었다면 false(무효)필요한 동의항목: 카카오계정(이메일) | X |
| is_email_verified Permission | Boolean | 이메일 인증 여부, true(인증된 이메일) 또는 false(인증되지 않은 이메일)필요한 동의항목: 카카오계정(이메일) | X |
| email Permission | String | 카카오계정 대표 이메일 필요한 동의항목: 카카오계정(이메일) 중요: 이메일 사용 시 주의 사항 | X |
| name_needs_agreement Permission | Boolean | 사용자 동의 시 이름 제공 가능 필요한 동의항목: 이름 | X |
| name Permission | String | 카카오계정의 이름 본인인증된 실명이 있다면 해당 값 제공 실명과 일치하지 않을 수 있으니, 실명이 필요할 경우 본인확인정보(이름) 사용 권장 필요한 동의항목: 이름 참고: 본인확인정보(이름)( legal_name)과 동시 제공 불가 | X |
| age_range_needs_agreement Permission | Boolean | 사용자 동의 시 연령대 제공 가능 필요한 동의항목: 연령대 | X |
| age_range Permission | String | 연령대1~9: 1세 이상 10세 미만10~14: 10세 이상 15세 미만15~19: 15세 이상 20세 미만20~29: 20세 이상 30세 미만30~39: 30세 이상 40세 미만40~49: 40세 이상 50세 미만50~59: 50세 이상 60세 미만60~69: 60세 이상 70세 미만70~79: 70세 이상 80세 미만80~89: 80세 이상 90세 미만90~: 90세 이상필요한 동의항목: 연령대 | X |
| birthyear_needs_agreement Permission | Boolean | 사용자 동의 시 출생 연도 제공 가능 필요한 동의항목: 출생 연도 | X |
| birthyear Permission | String | 출생 연도(YYYY 형식) 필요한 동의항목: 출생 연도 참고: 본인확인정보(생년월일)( legal_birth_date)과 동시 제공 불가 | X |
| birthday_needs_agreement Permission | Boolean | 사용자 동의 시 생일 제공 가능 필요한 동의항목: 생일 | X |
| birthday Permission | String | 생일(MMDD 형식) 필요한 동의항목: 생일 참고: 본인확인정보(생년월일)( legal_birth_date)과 동시 제공 불가 | X |
| birthday_type Permission | String | 생일 타입, SOLAR(양력) 또는 LUNAR(음력)필요한 동의항목: 생일 | X |
| is_leap_month Permission | Boolean | 생일의 윤달 여부 필요한 동의항목: 생일 | X |
| gender_needs_agreement Permission | Boolean | 사용자 동의 시 성별 제공 가능 필요한 동의항목: 성별 | X |
| gender Permission | String | 성별, female(여성) 또는 male(남성)필요한 동의항목: 성별 참고: 본인확인정보(성별)( legal_gender)과 동시 제공 불가 | X |
| is_kakaotalk_user Permission | Boolean | 카카오톡 서비스 가입 여부 필요한 동의항목: 카카오톡 서비스 가입 여부 | X |
| phone_number_needs_agreement Permission | Boolean | 사용자 동의 시 전화번호 제공 가능 필요한 동의항목: 카카오계정(전화번호) | X |
| phone_number Permission | String | 카카오계정의 전화번호 국내 번호인 경우 +82 00-0000-0000 형식해외 번호인 경우 자릿수와 '-'의 유무나 위치가 다를 수 있음 (참고: libphonenumber) 필요한 동의항목: 카카오계정(전화번호) | X |
| ci_needs_agreement Permission | Boolean | 사용자 동의 시 CI 참고 가능 필요한 동의항목: CI(연계정보) | X |
| ci Permission | String | 연계정보 필요한 동의항목: CI(연계정보) | X |
| ci_authenticated_at Permission | Datetime | 본인인증기관이 CI를 발급한 시각, UTC (RFC3339 internet date/time 형식) 필요한 동의항목: CI(연계정보) | X |
| account_id Permission Internal Only | Long | 카카오계정 ID | X |
| talk_user_id Permission Internal Only | Long | 카카오톡 회원번호 | X |
| daum_user_id Permission Internal Only | String | 카카오 및 공동체 서비스에만 제공하는 다음 회원 ID 카카오계정이 다음 통합 계정인 경우 제공 | X |
| display_id Permission | String | 카카오계정 대표 정보, 이메일 또는 전화번호 계정 상태에 따라 마스킹(Masking)된 이메일 또는 전화번호가 제공될 수 있음(참고) | X |
| unification_status Permission | Boolean | 카카오계정 통합 여부 | X |
| legal_name_needs_agreement Permission | Boolean | 사용자 동의 시 법정 실명 제공 가능 필요한 동의항목: 본인확인정보(이름) | X |
| legal_name Permission | String | 본인인증을 거친 카카오계정 사용자 실명 필요한 동의항목: 본인확인정보(이름) 참고: 이름( name)과 동시 제공 불가 | X |
| legal_birth_date_needs_agreement Permission | Boolean | 사용자 동의 시 법정 생년월일 제공 가능 필요한 동의항목: 본인확인정보(생년월일) | X |
| legal_birth_date Permission | String | 본인인증을 거친 법정 생년월일(yyyyMMDD 형식) 필요한 동의항목: 본인확인정보(생년월일) 참고: 생일( birthday), 생년월일(birthyear)과 동시 제공 불가 | X |
| legal_gender_needs_agreement Permission | Boolean | 사용자 동의 시 법정 성별 제공 가능 필요한 동의항목: 본인확인정보(성별) | X |
| legal_gender Permission | String | 본인인증을 거친 법정 성별female(여성) 또는 male(남성)필요한 동의항목: 본인확인정보(성별) 참고: 성별( gender)과 동시 제공 불가 | X |
| is_korean_needs_agreement Permission | Boolean | 사용자 동의 시 내국인 여부 제공 가능 필요한 동의항목: 본인확인정보(내/외국인) | X |
| is_korean Permission | Boolean | 본인인증을 거친 내국인 여부(대한민국 국적 보유 여부)true(내국인) 또는 false(외국인)필요한 동의항목: 본인확인정보(내/외국인) | X |
| account_creation_date_needs_agreement Permission | Boolean | 사용자 동의 시 카카오계정 가입일자 제공 가능 필요한 동의항목: 카카오계정 가입일자 | X |
| account_creation_date Permission | Datetime | 카카오계정 가입일자, UTC (RFC3339 internet date/time 형식) 필요한 동의항목: 카카오계정 가입일자 | X |
| is_spam_user Permission Internal Only | Boolean | 카카오계정의 스팸 의심 상태 여부 넓은 범위의 의심 상태로 해당 값에 대한 별도 처리 대신 참고 정보로 사용 권장 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| nickname | String | 닉네임 필요한 동의항목: 닉네임 또는 프로필 정보(닉네임/프로필 사진) | X |
| thumbnail_image_url | String | 프로필 미리보기 이미지 URL, 110px * 110px 또는 100px * 100px 필요한 동의항목: 프로필 사진 또는 프로필 정보(닉네임/프로필 사진) | X |
| profile_image_url | String | 프로필 이미지 URL, 640px * 640px 또는 480px * 480px 필요한 동의항목: 프로필 사진 또는 프로필 정보(닉네임/프로필 사진) | X |
| is_default_image | Boolean | 프로필 이미지 URL이 기본 프로필 이미지 URL인지 여부 사용자가 등록한 프로필 이미지가 없을 경우, 기본 프로필 이미지 제공
필요한 동의항목: 프로필 사진 또는 프로필 정보(닉네임/프로필 사진) | X |
| is_default_nickname | Boolean | 닉네임이 기본 닉네임인지 여부 사용자가 등록한 닉네임이 운영정책에 부합하지 않는 경우, "닉네임을 등록해주세요"가 기본 닉네임으로 적용됨
필요한 동의항목: 프로필 정보(닉네임/프로필 사진) 또는 닉네임 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| uuid Permission | String | 다른 사용자의 친구 정보에서 보여지는 해당 사용자의 고유 ID 카카오톡 친구 목록 조회 API 사용 권한 필요 | X |
| remaining_invite_count Permission | Integer | 카카오게임 전용 남은 일별 초대 메시지 전송 횟수 카카오톡 메시지 API 권한 필요 | X |
| remaining_group_msg_count Permission | Integer | 카카오게임 전용 남은 일별 그룹 메시지 전송 횟수 카카오톡 메시지 API 권한 필요 | X |
요청: 액세스 토큰 방식
- 사용자 정보 전체 받기
- 파라미터: 없음
curl -v -G GET "http://kapi.kakao.com/v2/internal/user/me" \-H "Authorization: Bearer ${ACCESS_TOKEN}"
요청: 서비스 앱 어드민 키 방식
- 회원번호를 전달해 카카오계정 ID 받기
- 파라미터
- 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 회원번호(user_id) - 응답에 포함할 사용자 정보의 키(
property_keys): 카카오계정 ID(kakao_account.account_id)
- 사용자 ID(
curl -v -G "http://kapi.kakao.com/v2/internal/user/me" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id_type=user_id" \-d "target_id=1376016924426814086" \--data-urlencode 'property_keys=["kakao_account.account_id"]'
요청: 서비스 앱 어드민 키 방식
- 회원번호를 전달해 카카오톡 회원번호 받기
- 파라미터
- 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 회원번호(user_id) - 응답에 포함할 사용자 정보의 키(
property_keys): 카카오톡 회원번호(kakao_account.talk_user_id)
- 사용자 ID(
curl -v -G "http://kapi.kakao.com/v2/internal/user/me" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id_type=user_id" \-d "target_id=1376016924426814086" \--data-urlencode 'property_keys=["kakao_account.talk_user_id"]'
요청: 서비스 앱 어드민 키 방식
- 고유ID로 요청
- 파라미터
- 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 고유ID(uuid)
- 사용자 ID(
curl -v -G "http://kapi.kakao.com/v2/internal/user/me" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id_type=uuid" \-d "target_id=YlBhUmVUYlB8S3tLektyS39NYVhvWGhfbg0"
요청: 위임 방식
- 회원번호를 전달해 카카오계정 ID 받기
- 파라미터
- 서비스 앱 키(
target_app_key) - 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 회원번호(user_id) - 응답에 포함할 사용자 정보의 키(
property_keys): 카카오계정 ID(kakao_account.account_id)
- 서비스 앱 키(
curl -v -G "http://kapi.kakao.com/v2/internal/user/me" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_app_key=${SERVICE_APP_KEY}" \-d "target_id_type=user_id" \-d "target_id=1376016924426542768" \--data-urlencode 'property_keys=["kakao_account.account_id"]'
요청: 위임 방식
- 회원번호를 전달해 카카오톡 회원번호 받기
- 파라미터
- 서비스 앱 ID(
target_app_id) - 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 회원번호(user_id) - 응답에 포함할 사용자 정보의 키(
property_keys): 카카오톡 회원번호(kakao_account.talk_user_id)
- 서비스 앱 ID(
curl -v -G "http://kapi.kakao.com/v2/internal/user/me" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_app_id=57669" \-d "target_id_type=user_id" \-d "target_id=1376016924426542768" \--data-urlencode 'property_keys=["kakao_account.talk_user_id"]'
요청: 위임 방식
- 회원번호를 전달해 카카오계정 ID 받기
- 파라미터
- 서비스 앱 ID(
target_app_id) - 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 회원번호(user_id) - 응답에 포함할 사용자 정보의 키(
property_keys): 카카오계정 ID(kakao_account.account_id)
- 서비스 앱 ID(
curl -v -G "http://kapi.kakao.com/v2/internal/user/me" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_app_id=57669" \-d "target_id_type=user_id" \-d "target_id=1376016924426542768" \--data-urlencode 'property_keys=["kakao_account.account_id"]'
요청: 위임 방식
- 액세스 토큰을 전달해 카카오계정 ID 받기
- 파라미터
- 액세스 토큰(
target_access_token) - 응답에 포함할 사용자 정보의 키(
property_keys): 카카오계정 ID(kakao_account.account_id)
- 액세스 토큰(
curl -v -G "http://kapi.kakao.com/v2/internal/user/me" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_access_token=${ACCESS_TOKEN}" \--data-urlencode 'property_keys=["kakao_account.account_id"]'
응답: 연결된(Registered) 사용자, 모든 정보 포함
- 아래 예제는 참고를 위해 모든 항목을 포함하고 있으나, 실제 API 응답에서 아래 정보는 둘 중 한 가지만 제공 가능합니다.
- 이름, 본인확인정보(이름)
- 성별, 본인확인정보(성별)
- 생일 및 출생연도, 본인확인정보(생년월일)
- 위 정보는 필요한 동의항목의 동시 설정이 불가능함
{"id": 1376016924426814086,// 카카오싱크 서비스에만 존재"synched_at": "2016-10-18T13:13:15Z",// 자동 연결 설정을 비활성화한 경우에만 존재"has_signed_up": true,"connected_at": "2016-10-18T13:13:15Z",// GROUP_APP_SUPPORTED 권한 필요"group_user_token": "${GROUP_USER_TOKEN}","properties": {"${CUSTOM_PROPERTY_KEY}": "${CUSTOM_PROPERTY_VALUE}"// ...},"kakao_account": {// 프로필 동의항목 필요"profile_needs_agreement": false,"profile": {"nickname": "홍길동","thumbnail_image_url": "http://yyy.kakao.com/.../img_110x110.jpg","profile_image_url": "http://yyy.kakao.com/dn/.../img_640x640.jpg","is_default_image": false,"is_default_nickname": false},// 이메일 동의항목 필요"email_needs_agreement": false,"is_email_valid": true,"is_email_verified": true,"email": "hong@sample.com",// 이름 동의항목 필요// legal_name과 함께 제공받을 수 없음"name_needs_agreement": false,"name": "홍길동",// 연령대 동의항목 필요"age_range_needs_agreement": false,"age_range": "20~29",// 출생 연도 동의항목 필요// legal_birth_date와 함께 제공받을 수 없음"birthyear_needs_agreement": false,"birthyear": "2002",// 생일 동의항목 필요// legal_birth_date와 함께 제공받을 수 없음"birthday_needs_agreement": false,"birthday": "1130","birthday_type": "SOLAR","is_leap_month": false,// 성별 동의항목 필요// legal_gender와 함께 제공받을 수 없음"gender_needs_agreement": false,"gender": "female",// 카카오톡 서비스 가입 여부 동의항목 필요"is_kakaotalk_user": true,// 전화번호 동의항목 필요"phone_number_needs_agreement": false,"phone_number": "+82 010-1234-5678",// CI(연계정보) 동의항목 필요"ci_needs_agreement": false,"ci": "${CI}","ci_authenticated_at": "2019-03-11T11:25:22Z",// 카카오계정ID 응답 권한 필요"account_id": 2137162,// 카카오톡 회원번호 응답 권한 필요"talk_user_id": 23456,// 다음 회원 ID 응답 권한 필요"daum_user_id": "_xDXX",// 카카오계정 대표 정보 응답 권한 필요"display_id": "hong@sample.com",// 카카오계정 통합 여부 응답 권한 필요"unification_status": false,// 본인확인정보(이름) 동의항목 필요// name과 함께 제공받을 수 없음"legal_name_needs_agreement": false,"legal_name": "홍길동",// 본인확인정보(생년월일) 동의항목 필요// birthday, birthyear와 함께 제공받을 수 없음"legal_birth_date_needs_agreement": false,"legal_birth_date": "20021130",// 본인확인정보(성별) 동의항목 필요// gender와 함께 제공받을 수 없음"legal_gender_needs_agreement": false,"legal_gender": "female",// 본인확인정보(내/외국인) 동의항목 필요"is_korean_needs_agreement": false,"is_korean": true,// 카카오계정 가입일자 동의항목 필요"account_creation_date_needs_agreement": false,"account_creation_date": "2015-02-03T06:13:53Z",// 카카오계정 스팸 의심 상태 여부 응답 권한 필요"is_spam_user": false},// 인하우스 및 제휴 앱에만 제공하는 추가 정보"for_partner": {// 카카오톡 친구 목록 조회 API 사용 권한 필요"uuid": "YVNjU2pZbkJ6T3xLfVFjVm9aaloO",// 카카오게임 전용"remaining_invite_count": 20,// 카카오게임 전용"remaining_group_msg_count": 5}}
응답: 연결된(Registered) 사용자, 일부 정보가 포함되지 않은 경우
{"id": 1376016924426814086,// 자동 연결 설정을 비활성화한 경우에만 존재"has_signed_up": true,"connected_at": "2016-10-18T13:13:15Z","properties": {"${CUSTOM_PROPERTY_KEY}": "${CUSTOM_PROPERTY_VALUE}"// ...},"kakao_account": {// 프로필 동의항목 필요"profile_needs_agreement": false,"profile": {"nickname": "홍길동","thumbnail_image_url": "http://yyy.kakao.com/.../img_110x110.jpg","profile_image_url": "http://yyy.kakao.com/dn/.../img_640x640.jpg"},// 이메일 동의항목 및 수집 후 제공 설정 필요"email_needs_agreement": false,// 연령대 동의항목 및 수집 후 제공 설정 필요"age_range_needs_agreement": false,// 생일 동의항목 및 수집 후 제공 설정 필요"birthday_needs_agreement": false,// 성별 동의항목 및 수집 후 제공 설정 필요"gender_needs_agreement": false,// 카카오톡 서비스 가입 여부 동의항목 필요"is_kakaotalk_user": true,// 전화번호 동의항목 필요"phone_number_needs_agreement": false,"phone_number": "+82 10-1234-1234",// 카카오계정 대표 정보 응답 권한 필요"display_id": "+82 10-1234-1234",// 카카오계정 통합 여부 응답 권한 필요"unification_status": false,// 본인확인정보(이름) 동의항목 필요"legal_name_needs_agreement": false,"legal_name": "홍길동",// 본인확인정보(생년월일) 동의항목 필요"legal_birth_date_needs_agreement": false,"legal_birth_date": "20021130",// 본인확인정보(성별) 동의항목 필요"legal_gender_needs_agreement": false,"legal_gender": "female",// 본인확인정보(내/외국인) 동의항목 필요"is_korean_needs_agreement": false,"is_korean": true},// 인하우스 및 제휴 앱에만 제공하는 추가 정보"for_partner": {// 카카오톡 친구 목록 조회 API 권한 필요"uuid": "YVNjU2pZbkJ6T3xLfVFjVm9aaloO"}}
응답: 연결 대기(Preregistered) 사용자
{"id": 1376016924426814086,// 자동 연결 설정을 비활성화한 경우에만 존재"has_signed_up": false,"properties": {"${CUSTOM_PROPERTY_KEY}": "${CUSTOM_PROPERTY_VALUE}"// ...},"kakao_account": {// 프로필 동의항목 필요"profile_needs_agreement": false,"profile": {"nickname": "홍길동","thumbnail_image_url": "http://yyy.kakao.com/.../img_110x110.jpg","profile_image_url": "http://yyy.kakao.com/dn/.../img_640x640.jpg"},// 이메일 동의항목 필요"email_needs_agreement": false,"is_email_valid": true,"is_email_verified": true,"email": "hong@gmail.com","age_range_needs_agreement": false,"birthyear_needs_agreement": false,"birthday_needs_agreement": false,"gender_needs_agreement": false,"is_kakaotalk_user": true,"ci_needs_agreement": false,// 카카오계정 통합 여부 응답 권한 필요"unification_status": false,"legal_name_needs_agreement": false,"legal_birth_date_needs_agreement": false,"legal_gender_needs_agreement": false,"is_korean_needs_agreement": false}}
응답: 사용자가 닉네임 동의항목만 동의한 경우
{"id": 1376016924429939660,"connected_at": "2021-06-25T02:21:56Z","properties": {"${CUSTOM_PROPERTY_KEY}": "${CUSTOM_PROPERTY_VALUE}"// ...},"kakao_account": {"profile_nickname_needs_agreement": false,"profile": {"nickname": "홍길동"}}}
응답: 사용자가 프로필 사진 동의항목만 동의한 경우
{"id": 1376016924429939660,"connected_at": "2021-06-25T02:21:56Z","properties": {"${CUSTOM_PROPERTY_KEY}": "${CUSTOM_PROPERTY_VALUE}"// ...},"kakao_account": {"profile_image_needs_agreement": false,"profile": {"thumbnail_image_url": "http://api1-kage.kakao.com/dn/xxIXk/bAOegubK0p8/j3QEU3knkSoG6KvruNy5zk/img_110x110.jpg","profile_image_url": "http://api1-kage.kakao.com/dn/xxIXk/bAOegubK0p8/j3QEU3knkSoG6KvruNy5zk/img_640x640.jpg","is_default_image": true}}}
앱의 사용자 회원번호 목록을 제공하는 API입니다. 이 API는 관리자를 위한 것으로, 앱 어드민 키를 사용하기 때문에 반드시 서버에서만 호출해야 합니다.
자세한 안내와 예제는 사용자 목록 조회를 참고합니다.
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET / POST | 카카오http://kapi.kakao.com/v2/internal/app/users공동체 https://kapi.kakao.com/v2/internal/app/users외부 https://kapi.kakao.com/v2/app/users | 서비스 앱 어드민 키 위임 |
앱과 연결된 사용자 여러 명의 정보를 받습니다.
헤더에 원하는 인증 정보를 담아 GET 또는 POST로 요청합니다. target_ids 파라미터로 정보를 조회할 사용자 ID 목록을 전달해야 합니다.
이 API의 기본 응답은 회원번호, 연결 시각과 같은 기본적인 정보만 포함합니다. property_keys 파라미터를 사용해 원하는 사용자 정보를 추가 요청할 수 있습니다. property_keys 파라미터 값은 요청할 사용자 정보와 사전 정의된 사용자 프로퍼티 키(Key)의 문자열(String) 배열로 구성해 아래와 같이 전달합니다.
property_keys=["id","has_signed_up"]
조회할 사용자 정보에 하위 항목이 존재하는 경우, 아래와 같이 상위 항목의 키에 온점(.)을 추가해 모든 하위 항목을 요청할 수 있습니다.
property_keys=["kakao_account.","properties."]
특정 하위 항목만 요청하려면, 아래와 같이 온점(.) 뒤에 하위 항목의 키를 명시해 전달합니다.
property_keys=["kakao_account.email","kakao_account.gender"]
세트로 구성된 응답은 관련 정보가 함께 전달됩니다. 예를 들어 property_keys에 "kakao_account.email"을 포함해 이메일 정보를 요청한 경우, 관련 정보인 kakao_account.email_needs_agreement, kakao_account.is_email_valid, kakao_account.is_email_verified가 응답에 함께 포함됩니다.
사용자 정보 전체를 요청하려면 아래와 같이 property_keys 파라미터 값을 전달합니다.
property_keys=["kakao_account.","properties.","for_partner.","has_signed_up"]
property_keys 파라미터 없이 특정 사용자의 전체 정보를 가져오려면 사용자 정보 조회 API를 사용해야 합니다.
아래와 같은 경우, 해당 사용자의 정보가 응답에 포함되지 않습니다.
- 존재하지 않는 사용자
- 카카오계정이 제재된 사용자
- 서비스 제공 조건에 맞지 않는 사용자
예를 들어, 14세 이상 이용 가능하도록 제한 연령이 적용된 앱에서 요청한 경우, 14세 미만 사용자의 정보는 응답에서 제외됩니다. 특정 사용자가 응답에서 제외되더라도 에러를 반환하지 않으므로 주의합니다.
앱에 응답 권한이 있는 경우, property_keys 파라미터를 전달하지 않아도 카카오계정 ID(account_id)와 카카오톡 회원번호(talk_user_id)가 응답에 포함됩니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_ids | String[] | 조회할 사용자 ID 목록 최대 100명의 사용자 정보 요청 가능 property_keys로 사용자 정보를 지정해 요청하는 경우, 최대 20명의 사용자 정보 요청 가능 | O |
| target_id_type | String | target_ids에 포함된 사용자 ID 타입, 아래 중 하나
user_id 또는 uuid만 사용 가능 | O |
| property_keys | String[] | 응답에 포함할 사용자 프로퍼티의 키 각 사용자 정보 및 앱 관리 페이지의 [카카오 로그인] > [고급] > [사용자 프로퍼티]에 지정된 키 사용 가능 미지정 시 기본 응답만 제공 | X |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
- 요청 대상 서비스 앱을 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키:
target_app_key - 서비스 앱 ID:
target_app_id
- 서비스 앱 키:
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_app_key | String | 사용자 정보를 조회할 서비스 앱의 키 | O(Optional) |
| target_app_id | String | 사용자 정보를 조회할 서비스 앱의 ID | O(Optional) |
| target_ids | String[] | 조회할 사용자 ID 목록 최대 100명의 사용자 정보 요청 가능 property_keys로 사용자 정보를 지정해 요청하는 경우, 최대 20명의 사용자 정보 요청 가능 | O |
| target_id_type | String | target_ids에 포함된 사용자 ID 타입, 아래 중 하나
user_id 또는 uuid만 사용 가능 | O |
| property_keys | String[] | 응답에 포함할 사용자 프로퍼티의 키 각 사용자 정보 및 앱 관리 페이지의 [카카오 로그인] > [고급] > [사용자 프로퍼티]에 지정된 키 사용 가능 미지정 시 기본 응답만 제공 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| elements | UserInfo[] | 사용자 정보 목록 여러 사용자 정보 조회 API의 기본 응답에서는 ID와 같은 일부 기본 정보만 포함 기본 응답 외 정보는 property_keys 파라미터로 지정해 응답에 포함하도록 요청 가능요청 가능한 정보의 종류는 사용자 정보 참고 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Long | 회원번호(user_id) | O |
| synched_at | Datetime | 카카오싱크 간편가입으로 로그인한 시각, UTC (RFC3339 internet date/time format) | X |
| connected_at | Datetime | 서비스에 연결 완료된 시각, UTC (RFC3339 internet date/time format) | X |
| kakao_account | KakaoAccount | 카카오계정 정보 | X |
| properties | JSON | 사용자 프로퍼티(key:value 형식)property_keys 파라미터로 특정 사용자 프로퍼티만 요청한 경우, 해당 사용자 프로퍼티 값만 제공 | X |
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 조회할 사용자 ID 목록(
target_ids) - 사용자 ID 타입(
target_id_type): 회원번호(user_id)
- 조회할 사용자 ID 목록(
curl -v -G GET "http://kapi.kakao.com/v2/internal/app/users" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_ids=[1376016924429759243]" \-d "target_id_type=user_id"
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 조회할 사용자 ID 목록(
target_ids) - 사용자 ID 타입(
target_id_type): 카카오계정 ID - 사용자 프로퍼티 키 목록(
property_keys): 프로필(kakao_account.profile), 이메일(kakao_account.email)
- 조회할 사용자 ID 목록(
curl -v -G GET "http://kapi.kakao.com/v2/internal/app/users" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_ids=[2137162]" \-d "target_id_type=account_id" \-d 'property_keys=["kakao_account.profile","kakao_account.email"]'
요청: 위임 방식
- 파라미터
- 서비스 앱 키(
target_app_key) - 조회할 사용자 ID 목록(
target_ids) - 사용자 ID 타입(
target_id_type): 회원번호(user_id)
- 서비스 앱 키(
curl -v -G GET "http://kapi.kakao.com/v2/internal/app/users" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_app_key=${SERVICE_APP_KEY}" \-d "target_ids=[1376016924429759243]" \-d "target_id_type=user_id"
요청: 위임 방식
- 파라미터
- 서비스 앱 ID(
target_app_id) - 조회할 사용자 ID 목록(
target_ids) - 사용자 ID 타입(
target_id_type): 카카오계정 ID
- 서비스 앱 ID(
curl -v -G GET "http://kapi.kakao.com/v2/internal/app/users" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_app_id=161495" \-d "target_ids=[2137162]" \-d "target_id_type=account_id"
응답: 기본 응답
[{"id": 1376016924429759241,// 카카오싱크 서비스에만 존재"synched_at": "2016-10-18T13:13:15Z","connected_at": "2021-02-26T02:38:10Z","kakao_account": {// 내부 API 요청 시에만 제공, 권한 필요"account_id": 2137162,// 내부 API 요청 시에만 제공, 권한 필요"talk_user_id": 209865432}}// ...]
응답: 사용자 정보 전체 요청 시 응답
- 사용자 정보 조회 응답 예제 참고
응답: 사용자 정보 프로필, 이메일 지정 요청
[{"id": 1376016924429759299,"connected_at": "2021-03-19T06:16:31Z","kakao_account": {"email_needs_agreement": false,"is_email_valid": true,"is_email_verified": true,"email": "test@kakaocorp.com"}}// ...]
사용자 프로퍼티 저장 기능은 사용자 프로퍼티인 properties에 값을 저장합니다. 키 값은 앱 관리 페이지의 [카카오 로그인] > [고급] > [사용자 프로퍼티]에 정의한 값을 사용해야 합니다. 사용자 프로퍼티에 대한 자세한 내용은 사용자 프로퍼티를 참고합니다.
자세한 안내와 예제는 사용자 프로퍼티 저장을 참고합니다.
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 카카오http://kapi.kakao.com/v1/internal/user/shipping_address공동체 https://kapi.kakao.com/v1/internal/user/shipping_address외부 https://kapi.kakao.com/v1/user/shipping_address | 액세스 토큰 서비스 앱 어드민 키 위임 |
사용자의 배송지 정보를 가져옵니다. 이 기능을 사용하려면 권한 및 동의항목 설정이 필요합니다. 자세한 안내는 배송지를 참고합니다.
헤더에 원하는 인증 방식의 정보를 담아 GET으로 요청하고, 성공 시 배송지 목록 또는 특정 배송지 정보를 받습니다. [배송지 정보] 동의항목이 설정돼 있지 않거나 사용자가 동의하지 않은 경우 배송지 정보를 제공하지 않습니다. 이 경우, 인가를 참고합니다. 이 외 에러 발생 시 에러 코드를 참고합니다.
이 API는 샌드박스 페이즈에서만 샘플 앱으로 테스트 가능합니다.
샘플 앱 이외의 앱으로 테스트하려면 해당 앱에 필요한 권한을 받아야 합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| address_id | Long | 배송지 정보가 많은 경우, 특정 배송지 정보만 얻고 싶을 때 배송지 ID 지정 | X |
| from_updated_at | Integer | 배송지 정보를 여러 페이지에 나눠 조회 시, 조회 기준이 되는 배송지 수정 시각(updated_at)유닉스 타임스탬프 형식의 시간 값(단위: 초) (기본값: 0) 참고: 배송지 페이지네이션 | X |
| page_size | Integer | 배송지 정보를 여러 페이지에 나눠 조회 시, 한 페이지에 포함할 배송지 개수 (기본값: 10, 최소값: 2) 참고: 배송지 페이지네이션 | X |
- 내부 API 요청 시에만 사용 가능합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_id | String | 배송지 정보를 가져올 사용자의 ID | O |
| target_id_type | String | target_id 타입, 아래 중 하나
user_id만 사용 가능 | O |
| address_id | Long | 배송지 정보가 많은 경우, 특정 배송지 정보만 얻고 싶을 때 배송지 ID 지정 | X |
| from_updated_at | Integer | 배송지 정보를 여러 페이지에 나눠 조회 시, 조회 기준이 되는 배송지 수정 시각(updated_at)유닉스 타임스탬프 형식의 시간 값(단위: 초) (기본값: 0) 참고: 배송지 페이지네이션 | X |
| page_size | Integer | 배송지 정보를 여러 페이지에 나눠 조회 시, 한 페이지에 포함할 배송지 개수 (기본값: 10, 최소값: 2) 참고: 배송지 페이지네이션 | X |
- 내부 API 요청 시에만 사용 가능합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
- 요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키:
target_app_key,target_id,target_id_type - 서비스 앱 ID:
target_app_id,target_id,target_id_type - 액세스 토큰:
target_access_token
- 서비스 앱 키:
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_app_key | String | 배송지 정보를 가져올 앱의 키 | O(Optional) |
| target_app_id | Long | 배송지 정보를 가져올 앱의 ID | O(Optional) |
| target_access_token | String | Bearer 타입의 액세스 토큰 사용 시, 배송지 정보를 가져올 사용자의 액세스 토큰 값 | O(Optional) |
| target_id | String | 배송지 정보를 가져올 사용자의 회원번호(user_id) | O(Optional) |
| target_id_type | String | target_id 타입, 아래 중 하나
| O(Optional) |
| address_id | Long | 배송지 정보가 많은 경우, 특정 배송지 정보만 얻고 싶을 때 배송지 ID 지정 | X |
| from_updated_at | Integer | 배송지 정보를 여러 페이지에 나눠 조회 시, 조회 기준이 되는 배송지 수정 시각(updated_at)유닉스 타임스탬프 형식의 시간 값(단위: 초) (기본값: 0) 참고: 배송지 페이지네이션 | X |
| page_size | Integer | 배송지 정보를 여러 페이지에 나눠 조회 시, 한 페이지에 포함할 배송지 개수 (기본값: 10, 최소값: 2) 참고: 배송지 페이지네이션 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| user_id | Long | 배송지 정보를 가져온 사용자 회원번호 | X |
| shipping_addresses_needs_agreement | Boolean | 사용자 동의 시 배송지 정보 제공 가능 | X |
| shipping_addresses | ShippingAddress[] | 사용자의 배송지 정보 리스트 최신순 정렬 기본 배송지는 수정 시각과 관계 없이 첫 번째에 위치 | X |
has_shipping_addresses: Deprecated, 각 사용자 정보 값 소유 여부(Boolean), 해당 사용자 정보의 제공 가능 여부를 확인하는 용도로 사용할 수 없음(참고: needs_agreement)
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Long | 배송지 ID | O |
| name | String | 배송지명 | X |
| is_default | Boolean | 기본 배송지 여부 | O |
| updated_at | Integer | 배송지 수정 시각 유닉스 타임스탬프 형식의 시간 값(단위: 초) | X |
| type | String | 배송지 타입, 구주소(OLD, 지번 및 번지 주소) 또는 신주소(NEW, 도로명 주소) | X |
| base_address | String | 우편번호 검색시 채워지는 기본 주소 | X |
| detail_address | String | 기본 주소에 추가하는 상세 주소 | X |
| receiver_name | String | 수령인 이름 | X |
| receiver_phone_number1 | String | 수령인 연락처 | X |
| receiver_phone_number2 | String | 수령인 추가 연락처 | X |
| zone_number | String | 신주소 우편번호, 신주소인 경우 반드시 존재 | X |
| zip_code | String | 구주소 우편번호 구주소는 우편번호를 소유하지 않는 경우가 있어, 구주소라도 해당 값이 없을 수 있음 | X |
요청: 액세스 토큰 방식
- 특정 배송지만 요청
- 파라미터
- 배송지 ID(
address_id)
- 배송지 ID(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/shipping_address" \-H "Authorization: Bearer ${ACCESS_TOKEN}" \-d "address_id=321"
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 카카오계정 ID(account_id)
- 사용자 ID(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/shipping_address" \-d "target_id=12345&target_id_type=account_id" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}"
요청: 위임 방식
- 파라미터
- 서비스 앱 키(
target_app_key) - 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 카카오계정 ID(account_id)
- 서비스 앱 키(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/shipping_address" \-d "target_id=12345&target_id_type=account_id" \-d "target_app_key=${SERVICE_APP_KEY}" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}"
응답: 전체 배송지 목록 요청
{"user_id": 12345,"shipping_addresses_needs_agreement": false,"shipping_addresses": [{"default": true,"id": 319,"name": "에스동","is_default": true,"updated_at": 1538448856,"type": "NEW","base_address": "경기 성남시 분당구 판교역로 231 (삼평동, 에이치스퀘어 에스동)","detail_address": "6층","receiver_name": "판교","receiver_phone_number1": "031-123-2345","receiver_phone_number2": "","zone_number": "13494","zip_code": "463-400"},{"default": false,"id": 320,"name": "에스동","is_default": false,"updated_at": 1538450389,"type": "OLD","base_address": "경기 성남시 분당구 삼평동 680 (삼평동, 에이치스퀘어 에스동)","detail_address": "6층","receiver_name": "판교2","receiver_phone_number1": "010-0056-1234","receiver_phone_number2": "","zone_number": "13494","zip_code": "463-400"},{"default": false,"id": 321,"name": "엔동","is_default": false,"updated_at": 1538450195,"type": "OLD","base_address": "경기 성남시 분당구 삼평동 681 (삼평동, 에이치스퀘어 엔동)","detail_address": "7층","receiver_name": "판교4","receiver_phone_number1": "123-456-2225","receiver_phone_number2": "","zone_number": "13494","zip_code": "463-400"}]}
응답: 특정 배송지만 요청
{"user_id": 12345,"shipping_addresses": [{"default": false,"id": 321,"name": "엔동","is_default": false,"updated_at": 1538450195,"type": "OLD","base_address": "경기 성남시 분당구 삼평동 681 (삼평동, 에이치스퀘어 엔동)","detail_address": "7층","receiver_name": "판교4","receiver_phone_number1": "123-456-2225","receiver_phone_number2": "","zone_number": "13494","zip_code": "463-400"}]}
응답: 앱에 배송지 조회 API 권한이 없는 경우
{"msg": "permission denied","code": -5}
응답: 앱에 배송지 정보 동의항목이 설정되어 있지 않은 경우
{"msg": "[XXXXX] App disabled [shipping_address] scopes for [USER_SHIPPING] API on developers.kakao.com. Enable it first.","code": -3}
응답: 앱에 배송지 정보 동의항목이 설정돼 있지만 사용자가 동의하지 않은 경우
{"user_id": 12345,"shipping_addresses_needs_agreement": true}
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 카카오http://kapi.kakao.com/v2/internal/user/id공동체 https://kapi.kakao.com/v2/internal/user/id | 액세스 토큰 서비스 앱 어드민 키 위임 |
특정 사용자 ID로 다른 유형 ID를 조회합니다. 이 API는 카카오 및 공동체에서 사용자의 특정 ID로 다른 유형 ID를 조회하는데 사용할 수 있습니다. 카카오계정 ID(account_id), 카카오톡 회원번호(talk_id)를 제공받으려면 권한이 필요합니다. 회원번호(user_id)의 경우, 해당 사용자에게 회원번호가 존재하는 경우에만 값을 제공합니다.
헤더에 원하는 인증 정보를 담아 GET으로 요청합니다. 요청 시 조회 대상 ID 유형을 results로 전달해야 합니다. results=user_id,uuid와 같이 여러 ID 유형으로의 조회를 요청할 수 있습니다.
조회 대상 카카오계정의 제재 또는 휴면 상태 여부와 상관없이 응답을 받으려면 skip_account_check를 true로 포함해야 하며, 별도 권한이 필요합니다.
요청 성공 시 응답은 result 파라미터로 지정한 ID 유형별 ID 값입니다. 각 ID 값은 제공 조건을 만족해야만 응답에 포함됩니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| results | String | 조회할 ID 종류, 아래 중 하나 이상의 값 사용 가능, 여러 개 사용 시 쉼표(,)로 구분
account_id,talk_id) | O |
| skip_account_check Permission | Boolean | 조회 대상 카카오계정의 제재 또는 휴면 상태 무시 여부
| X |
- 내부 API 요청 시에만 사용 가능합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_id | String | 사용자 ID | O |
| target_id_type | String | target_id 타입, 아래 중 하나
참고: ID 종류 | O |
| results | String | 조회할 ID 종류, 아래 중 하나 이상의 값 사용 가능, 여러 개 사용 시 쉼표(,)로 구분
account_id,talk_id) | O |
| skip_account_check | Boolean | 조회 대상 카카오계정의 제재 또는 휴면 상태 무시 여부
| X |
- 내부 API 요청 시에만 사용 가능합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
- 요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키:
target_app_key,target_id,target_id_type - 서비스 앱 ID:
target_app_id,target_id,target_id_type - 액세스 토큰:
target_access_token
- 서비스 앱 키:
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_app_key | String | 앱 키 | O(Optional) |
| target_app_id | Long | 앱 ID | O(Optional) |
| target_access_token | String | 사용자의 액세스 토큰 값 | O(Optional) |
| target_id | String | 사용자 ID | O(Optional) |
| target_id_type | String | target_id 타입, 아래 중 하나
참고: ID 종류 | O(Optional) |
| results | String | 조회할 ID 종류, 아래 중 하나 이상의 값 사용 가능, 여러 개 사용 시 쉼표(,)로 구분
account_id,talk_id) | O |
| skip_account_check | Boolean | 조회 대상 카카오계정의 제재 또는 휴면 상태 무시 여부
| X |
- 요청 시
results파라미터로 지정한 ID 유형 중 제공 가능한 항목만 응답에 포함
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| user_id | Long | 회원번호 제공 조건: 해당 사용자의 회원번호가 존재하는 경우 | X |
| account_id | Integer | 카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한이 있는 경우 | X |
| talk_id | Long | 카카오톡 회원번호 제공 조건: 해당 사용자가 카카오톡 사용자이고 카카오톡 회원번호 응답 권한이 있는 경우 | X |
| uuid | String | 사용자 고유 ID | X |
요청: 액세스 토큰 방식
- 파라미터
- 조회할 ID 유형: 카카오계정 ID(account_id), 카카오톡 회원번호(talk_id)
curl -v -G GET "http://kapi.kakao.com/v2/internal/user/id" \-H "Authorization: Bearer ${ACCESS_TOKEN}" \-d "results=account_id,talk_id"
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 회원번호(user_id) - 조회할 ID 유형: 카카오톡 회원번호(talk_id), 고유 ID(uuid)
- 사용자 ID(
curl -v -G GET "http://kapi.kakao.com/v2/internal/user/id" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id=12345" \-d "target_id_type=user_id" \-d "results=talk_id,uuid"
요청: 위임 방식
- 파라미터
- 서비스 앱 키(
target_app_key) - 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 카카오계정 ID(account_id) - 조회할 ID 유형: 회원번호(user_id), 고유 ID(uuid)
- 서비스 앱 키(
curl -v -G GET "http://kapi.kakao.com/v2/internal/user/id" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_id=12345" \-d "target_id_type=account_id" \-d "target_app_key=${SERVICE_APP_KEY}" \-d "results=user_id,uuid"
응답
// HTTP/1.1 200 OK{"user_id": 1376016924429759243, // 해당 사용자의 회원번호가 존재하는 경우"account_id": 2137162, // 카카오계정ID 응답 권한 필요"talk_id": 700119942, // 카카오톡 회원번호 응답 권한 필요"uuid": "YlBhUmVUYlB8S3tLektyS39NYVhvWGhfbg0"}
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 카카오http://kapi.kakao.com/v1/internal/user/group_info공동체 https://kapi.kakao.com/v1/internal/user/group_info외부 https://kapi.kakao.com/v1/user/group_info | 액세스 토큰 서비스 앱 어드민 키 |
사용자와 연결된 앱이 그룹 앱일 경우, 그룹에 속한 다른 연결된 앱의 기본 정보와 사용자 회원번호를 받습니다. 그룹 앱은 2개 이상의 앱을 하나의 그룹으로 묶고, 사용자 연결 상태 및 정보를 그룹 안에서 공유할 수 있는 기능입니다. 예를 들어 여러 서비스에서 하나의 통합 멤버십 서비스를 사용한다면, 해당 서비스들을 한 그룹으로 묶어 그룹 내 서비스들에 대한 사용자의 연결 상태를 각 그룹 앱에서 조회할 수 있습니다. 자세한 정보는 그룹 앱을 참고합니다.
액세스 토큰, 또는 앱 어드민 키와 회원번호를 헤더에 담아 GET으로 요청하며, 응답은 그룹 사용자 토큰과 연결되어 있는 앱별 회원번호 목록을 포함합니다. 응답의 회원번호 목록인 group_info에는 해당 사용자가 연결되어 있는 앱의 정보만 포함되므로, 이 목록에 그룹 내 특정 앱들이 포함되어 있지 않다면 사용자가 그룹 내 앱 중 해당 앱은 이용하지 않는다는 의미입니다.
- 각 그룹 앱에서 카카오 API를 호출하려면 각 앱에서 사용자가 로그인 및 수동 연결을 해야 합니다. 그룹에 속해 있는 앱이라도 사용자가 연결되어 있지 않은 경우에는 앱 기본 정보와 사용자 회원번호를 제공하지 않습니다.
- 카카오싱크 간편가입 사용 시, 각 앱의 서비스 약관을 별도로 등록해야 합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 | O |
- 내부 API 요청 시에만 사용 가능합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_id | String | 그룹 내 사용자 정보를 가져올 사용자 ID | O |
| target_id_type | String | target_id 타입, 아래 중 하나
| O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| group_user_token | String | 해당 앱이 그룹에 속해 있을 때만 존재 그룹에서 맵핑 정보로 사용할 수 있는 값 그룹 정보가 변경되면 바뀔 수 있는 값이니 id로 사용할 수 없음 | X |
| group_info | UserGroupInfoResult[] | 그룹에 속한 앱 중 사용자가 가입한 앱의 정보와 해당 앱에서의 회원번호(user_id) | X |
| 이름 | 타입 | 설명 |
|---|---|---|
| user_id | Long | 회원번호, 이 앱에서의 사용자 식별자 |
| app | AppDefaultInfo | 앱 정보 |
| 이름 | 타입 | 설명 |
|---|---|---|
| id | Integer | 앱 ID |
| name | String | 앱 이름 |
| company | String | 앱 회사명 |
요청: 액세스 토큰 방식
- 파라미터: 없음
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/group_info" \-H "Authorization: Bearer ${ACCESS_TOKEN}"
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 카카오계정 ID(account_id)
- 사용자 ID(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/group_info" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id=200937" \-d "target_id_type=account_id"
응답
// HTTP/1.1 200 OK{"group_info": [{"app": {"company": "무지홀딩스","id": 12345,"name": "무지중고장터"},"user_id": 123456789},{"app": {"company": "무지홀딩스","id": 67890,"name": "무지여행사"},"user_id": 987654321}],"group_user_token": "${GROUP_USER_TOKEN}"}
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 카카오https://kapi.kakao.com/v1/internal/user/generate/group_user_token/batch공동체 https://kapi.kakao.com/v1/internal/user/generate/group_user_token/batch | 서비스 앱 어드민 키 |
카카오계정 ID(accountId)를 그룹 사용자 토큰으로 변경합니다. 그룹 사용자 토큰에 대한 정보는 그룹 앱을 참고합니다.
이 API는 그룹 앱만 사용할 수 있으며, 사용하려면 인하우스, 공동체 모두 [서비스] API플랫폼 아지트로 API 사용 권한을 신청해야 합니다. 기존에 사용되던 카카오계정 ID를 그룹 사용자 토큰으로 변경하기 위해 제공되며, 그룹 사용자 토큰을 새로 만들기 위해 사용할 수 없습니다.
헤더에 앱 어드민 키를 담아 GET로 요청합니다. 요청 시 그룹 토큰으로 변경할 카카오계정 ID 목록을 전달해야 합니다.
요청 성공 시 카카오계정 ID별로 생성된 그룹 토큰 정보가 담긴 JSON 객체를 받습니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| account_ids | Integer[] | 카카오계정 ID 목록 최대 200개의 카카오계정 ID 전달 가능 | O |
| registered_user_only | Boolean | 그룹 사용자 토큰을 생성할 사용자 범위 (기본값: true)
중요: false로 지정 시, 카카오 계정 탈퇴 또는 서비스에 가입되지 않은 모든 사용자에 대해 그룹 토큰을 생성하므로 유의 필요 | X |
- 요청한 사용자의 카카오계정 ID와 생성된 그룹 사용자 토큰이 키와 값으로 구성된 객체
- 예:
{"${ACCOUNT_ID}": "${GROUP_USER_TOKEN}", ...}
- 예:
- 동일한 카카오계정 ID 목록을 요청하더라도
registered_user_only값에 따라 반환되는 대상이 다를 수 있음
요청: 앱과 연결된 사용자만 그룹 토큰 생성하기
curl -v -G GET "https://kapi.kakao.com/v1/internal/user/generate/group_user_token/batch" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "registered_user_only=true" \--data-urlencode "account_ids=[236788, 236789, 236790, 236791, 268520]"
요청: 탈퇴 계정을 포함한 모든 사용자의 그룹 토큰 생성하기
curl -v -G GET "https://kapi.kakao.com/v1/internal/user/generate/group_user_token/batch" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "registered_user_only=false" \--data-urlencode "account_ids=[236788, 236789, 236790, 236791, 268520]"
응답: 앱과 연결된 사용자만 그룹 토큰 생성
// HTTP/1.1 200 OK{"236790": "49Hi1OPabxyzxyzxyzxyz", // 휴면 계정"236788": "13Hi1OPabxyzxyzxyzxyz", // 정상 계정"236789": "24Hi1OPabxyzxyzxyzxyz" // 제제 계정}
응답: 탈퇴 계정을 포함한 모든 사용자의 그룹 토큰 생성
// HTTP/1.1 200 OK{"236790": "49Hi1OPabxyzxyzxyzxyz", // 휴면 계정"236788": "13Hi1OPabxyzxyzxyzxyz", // 정상 계정"236789": "24Hi1OAbxyzxyzxyzxyz", // 제제 계정"236791": "30Hi1OAbxyzxyzxyzxyz", // 서비스 탈퇴(연결 해제) 계정"268520": "18Hi1OAbxyzxyzxyzxyz-rY6MT2x_bE8MaE" // 계정 탈퇴}
응답: 실패, 그룹 앱에 속하지 않은 앱으로 요청한 경우
// HTTP/1.1 400 Bad Request{"msg": "only group app allowed","code": -2}
응답: 200개를 초과하는 카카오계정 ID를 요청한 경우
// HTTP/1.1 400 Bad Request{"msg": "accountIds size must smaller or equal to 200","code": -2}
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 카카오http://kapi.kakao.com/v3/internal/user/app공동체 https://kapi.kakao.com/v3/internal/user/app | 위임 |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| 필요: 공동체 앱 | 어드민 키 카카오 로그인 활성화 | 필요: 연결, 연결 대기, 연결 없음 | - |
사용자와 연결된 앱의 정보를 조회합니다. 아래와 같은 용도로 사용할 수 있습니다.
- 사용자와 앱의 연결 상태 확인
- 응답의
user_status값으로 사용자의 앱 연결 완료 여부 가능 - 앱과 연결되지 않았고, 회원번호도 존재하지 않는 사용자를 대상으로 요청할 경우 에러(-101) 응답 반환
- 응답의
- 앱 정보 조회
- 플랫폼 앱에서 사용자와 연결된 각 서비스 앱의 정보 조회
- 요청 시
results파라미터로 조회할 항목 선택 가능
헤더에 플랫폼 앱 어드민 키를 포함하고, 파라미터로 요청 대상 앱과 사용자를 지정해 GET으로 요청합니다.
요청 성공 시 사용자 정보와 앱 정보가 담긴 JSON 객체를 받습니다. 사용자 정보 중 카카오계정 ID(account_id), 카카오톡 회원번호(talk_id)는 권한이 있는 앱에서 요청한 경우에만 응답에 포함됩니다.
응답의 앱 정보는 앱 기본 정보와 함께 results 파라미터로 요청한 추가 정보를 포함합니다. 요청 가능한 추가 정보의 종류는 아래 results: 추가 정보 표를 참고합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
- 요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키:
target_app_key,target_id,target_id_type - 서비스 앱 ID:
target_app_id,target_id,target_id_type - 액세스 토큰:
target_access_token
- 서비스 앱 키:
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_app_key | String | 연결 정보를 확인할 서비스 앱의 키 | O(Optional) |
| target_app_id | Integer | 앱 연결 정보를 가져올 서비스 앱의 ID | O(Optional) |
| target_access_token | String | 앱 연결 정보를 가져올 사용자의 액세스 토큰 값 | O(Optional) |
| target_id | String | 연결된 앱 정보를 확인할 사용자 ID | O(Optional) |
| target_id_type | String | target_id 타입, 아래 중 하나
| O(Optional) |
| results | String | 앱과 사용자의 기본정보 외에 가져오고 싶은 추가 정보를 지정하는 파라미터 전달한 키 값에 따라 응답 구성 다름 (예: "results=app_key,app_scopes")(기본값: null)아래 중 원하는 정보의 키를 하나의 문자열에 쉼표(,)로 구분해 전달:
| X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| user_id | Long | 회원번호 | O |
| user_status | String | 사용자 상태, 아래 중 하나
| O |
| account_id | Integer | 사용자의 카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유 | X |
| talk_user_id | Long | 사용자의 카카오톡 회원번호 제공 조건: 카카오톡 회원번호(talk_id) 응답 권한 보유 | X |
| auth_level | String | 앱의 연령인증 레벨, 아래 중 하나
제공 조건: 조회 대상 앱이 카카오게임 중 2차 연령인증이 설정된 리치보드게임인 경우 | X |
| age_limit | Integer | 앱에 설정된 제한 연령 제공 조건: 조회 대상 앱이 카카오게임 중 2차 연령인증이 설정된 리치보드게임인 경우 | X |
| id | Integer | 앱 ID | O |
| name | String | 앱 이름 | O |
| company | String | 회사명 | X |
| type | String | 앱 타입, 아래 중 하나
| O |
| status | String | 앱 상태, 아래 중 하나
| O |
| category | String | 앱 카테고리 | O |
| phase | String | 테스트 앱 여부, 아래 중 하나
| O |
| owner_developer | DeveloperInfo | 앱의 소유자(OWNER)인 개발자 정보 제공 조건: 요청 시 results 파라미터에 owner_developer를 포함한 경우 | X |
| app_business_info | AppBusinessInfo | 앱의 비즈니스 정보 제공 조건: 요청 시 results 파라미터에 app_business_info를 포함한 경우 | X |
| icon_image_url | String | 앱 아이콘 이미지 URL(http 형식) 제공 조건: 요청 시 results 파라미터에 app_detail를 포함한 경우 | X |
| secure_icon_image_url | String | 앱 아이콘 이미지 URL(https 형식) 제공 조건: 요청 시 results 파라미터에 app_detail를 포함한 경우 | X |
| user_management | String | 카카오 로그인 활성화 여부, 아래 중 하나
제공 조건: 요청 시 results 파라미터에 아래 키 중 하나라도 포함한 경우
| O |
| app_keys | AppKey[] | 조회 대상인 앱의 앱 키 목록 target_app_key로 요청한 경우, 요청한 키가 REST API 키가 아니라면 응답에 REST API 키 포함, 위 제공 조건에 만족할 경우 해당 앱 키와 REST API 키를 포함하고 권한이 없는 경우 해당 앱 키만 응답제공 조건: 요청 시 results 파라미터에 app_key_detail 또는 app_key를 포함하고 target_app_key로 요청 시 포함한 경우API 응답 권한 보유 시에만 포함 | X |
| execution_url | ExecutionUrl[] | OS별 앱 실행 커스텀 URL 제공 조건: 요청 시 results 파라미터에 app_key_detail를 포함한 경우 | X |
| market_url | MarketUrl[] | OS별 앱 설치 커스텀 URL 제공 조건: 요청 시 results 파라미터에 app_key_detail를 포함한 경우 | X |
| app_key_type | String | 앱 키 타입으로 아래 중 하나
중요: target_app_key로 요청한 경우, 해당 앱 키의 타입target_app_id로 요청 시, 권한에 따라 해당 앱의 앱 키 제공(현재 REST_API_KEY만 지원)제공 조건: 요청 시 results 파라미터에 app_key를 포함한 경우 | X |
| app_key | String | app_key_type에 해당하는 앱 키 값 제공 조건: 요청 시 results 파라미터에 app_key를 포함한 경우 | X |
| kakao_sync | String | 카카오싱크 간편가입 활성화 여부, 아래 중 하나
중요: 카카오 로그인이 비활성화되어 있어 응답의 user_management 값이 OFF인 경우 제공하지 않음카카오싱크 검수를 통과하지 않아 간편가입 기능의 사용 권한이 없는 경우의 값은 OFF제공 조건: 요청 시 results 파라미터에 kakao_sync를 포함한 경우 | X |
| service_terms | ServiceTerm[] | 카카오싱크 간편가입을 사용하는 앱의 서비스 약관 정보 카카오싱크 검수를 통과해 약관이 등록된 경우 서비스 약관 정보 제공 카카오 로그인이 비활성화되어 있어 응답의 user_management 값이 OFF인 경우 제공하지 않음제공 조건: 요청 시 results 파라미터에 kakao_sync를 포함한 경우 | X |
| biz_plugin | BizPlugin | 회원가입 플러그인을 사용하는 경우 포함, t1, t2 URL제공 조건: 회원가입 플러그인 권한 보유한 경우, 요청 시 results 파라미터에 kakao_sync를 포함한 경우 | X |
| ecp_type | String | ECP 타입(회사명) ECP앱이 아닌 경우 미제공, 아래 중 하나
제공 조건: 요청 시 results 파라미터에 ecp를 포함한 경우 | X |
| kakao_biz_service | Boolean | 비즈니스 성격(B2B)의 서비스인지 여부 제공 조건: 요청 시 results 파라미터에 kakao_biz_service를 포함한 경우 | O |
| not_allowed_under14 | Boolean | 14세 미만 사용자 앱 제한 여부
제공 조건: 요청 시 results 파라미터에 not_allowed_under14를 포함한 경우 | O |
| user_management | String | 카카오 로그인 활성화 여부, 아래 중 하나
제공 조건: 요청 시 results 파라미터에 아래 키 중 하나라도 포함한 경우
| O |
| app_scopes | AppScope[] | 앱에 설정된 동의항목 목록 제공 조건: 카카오 로그인이 활성화되어 있어 응답의 user_management 값이 ON인 경우, 요청 시 results 파라미터에 app_scopes를 포함한 경우 | X |
| app_channel_scopes | AppScope[] | 앱에 설정된 채널별 동의항목 목록 제공 조건: 카카오 로그인이 활성화되어 있어 응답의 user_management 값이 ON인 경우, 요청 시 results 파라미터에 app_channel_scopes를 포함한 경우 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Integer | 개발자 ID | O |
| account_id | Integer | 개발자의 카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유 | X |
| registered_at | String | 개발자 가입 시각(RFC3339 internet date/time 형식) | O |
| deactivated | Boolean | 개발자 계정이 휴면 계정 탈퇴 처리로 탈퇴된 경우, 서비스에 영향을 주기 않기 위해 탈퇴된 상태로 소유자(OWNER) 정보가 남으며, 이 경우에만 true 값으로 제공 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| app_key_type | String | 앱 키 타입으로 아래 중 하나
중요: target_app_key로 요청한 경우, 해당 앱 키의 타입target_app_id로 요청 시, 권한에 따라 해당 앱의 앱 키 제공(현재 REST_API_KEY만 지원)제공 조건: 요청 시 results 파라미터에 app_key_detail를 포함한 경우 | X |
| app_key | String | app_key_type에 해당하는 앱 키 값 제공 조건: 요청 시 results 파라미터에 app_key_detail를 포함한 경우 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| biz_app | Boolean | 비즈 앱 여부, 앱의 사업자번호 등록 여부 | O |
| biz_plus_friends_app | Boolean | 비즈채널 앱 여부, 앱과 연결된 비즈니스 채널 존재 여부 | O |
| business_number | String | 앱에 등록된 사업자번호 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| platform | String | 플랫폼 정보, 아래 중 하나
| O |
| pkgnames | String[] | platform이 android인 경우, 앱에 설정된 안드로이드 패키지 이름(Package name) 목록 | X |
| urls | String[] | platform이 iOS나 iPad인 경우, 앱에 설정된 커스텀 URL 스킴platform이 web인 경우, 앱에 설정된 웹 도메인 목록 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| platform | String | 플랫폼 정보, 아래 중 하나
| O |
| urls | String[] | 앱 설치 URL 목록 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| tag | String | 약관 태그(tag) 서비스 약관 선택해 동의 요청에 사용 | O |
| title_ko | String | 한글 제목 | O |
| title_en | String | 영문 제목 | O |
| title_ja | String | 일본어 제목 | X |
| title_zh | String | 중국어(간체) 제목 | X |
| title_zhtw | String | 중국어(번체) 제목 | X |
| url | String | 상세 URL | X |
| required | Boolean | 해당 약관이 필수 동의해야 하는 항목인지 여부, 아래 중 하나
| O |
| order | Integer | 약관이 보여지는 순서 | O |
| created_at | Datetime | 약관 생성 시각(RFC3339 internet date/time 형식) | O |
| updated_at | Datetime | 약관 수정 시각(RFC3339 internet date/time 형식) | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| third_terms_info_uri | String | t1, 공통플러그인용, 서비스 제공자(Third party)의 약관을 가져오는 URL제공 조건: 공통플러그인 권한 보유 | X |
| third_terms_agreement_uri | String | t2, 공통플러그인용, 서비스 제공자(Third party)의 약관에 동의하는 URL제공 조건: 공통플러그인 권한 보유 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | String | 동의항목 ID | O |
| display | String | 동의항목 이름, KA 헤더의 언어(language)에 따라 한글 또는 영어로 제공 | O |
| scope_type | String | 동의항목 타입, 아래 중 하나
| O |
| required | Boolean | 필수 동의항목으로 설정되었는지 여부 해당 동의항목을 사용하도록 설정하지 않은 경우 false | O |
| collecting | Boolean | 수집 후 제공 설정 여부 해당 동의항목을 사용하도록 설정하지 않았고, 수집 후 제공을 설정하지 않았다면 false | O |
| using | Boolean | 사용 중인 동의항목인지 여부 해당 동의항목을 필수 동의 또는 선택 동의로 설정한 경우 true, 사용안함으로 설정한 경우 false | O |
| has_permission | Boolean | 동의항목을 설정할 수 있는 권한 소유 여부 해당 동의항목을 설정할 수 있는 권한이 있는 경우 true, 권한이 없는 경우 false | O |
요청: 위임 방식
- 파라미터
- 서비스 앱 키(
target_app_key) - 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 카카오계정 ID(account_id) - 추가 정보 요청(
results): 앱의 소유자인 개발자 정보(owner_developer)
- 서비스 앱 키(
curl -v -G GET "http://kapi.kakao.com/v3/internal/user/app" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_id=200937" \-d "target_id_type=account_id" \-d "target_app_key=${SERVICE_APP_KEY}" \-d "results=owner_developer"
요청: 위임 방식
- 파라미터
- 서비스 앱 ID(
target_app_id) - 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 카카오계정 ID(account_id) - 추가 정보 요청(
results): 앱의 소유자인 개발자 정보(owner_developer), 앱의 비즈니스 정보(app_business_info), 앱 상세 정보(app_detail)
- 서비스 앱 ID(
curl -v -G GET "http://kapi.kakao.com/v3/internal/user/app" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_id=200937" \-d "target_id_type=account_id" \-d "target_app_id=259500" \-d "results=owner_developer,app_business_info,app_detail"
요청: 위임 방식
- 파라미터
- 액세스 토큰(
target_access_token) - 추가 정보 요청(
results): 앱에 설정된 동의항목 목록(app_scopes)
- 액세스 토큰(
curl -v -G GET "http://kapi.kakao.com/v3/internal/user/app" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_access_token=${ACCESS_TOKEN}" \-d "results=app_scopes"
응답: 연결된 사용자
results파라미터를 사용하지 않은 경우의 기본 응답 예제입니다.
// HTTP/1.1 200 OK{"id": 977071,"name": "Sample","company": "SampleCompany","type": "KAKAO","status": "ACTIVE","category": "Book_Reference","user_id": 1376016924429759243,"user_status": "REGISTERED","account_id": 2137162, //권한 필요"talk_user_id": 700119942 //권한 필요}
응답: 연결된 사용자, app_details 요청 정보 포함
- 요청 시
results파라미터로app_details를 전달한 경우의 응답 예제입니다.
// HTTP/1.1 200 OK{"id": 977071,"name": "Sample","company": "SampleCompany","type": "KAKAO","status": "ACTIVE","category": "Book_Reference","icon_image_url": "http://k.kakaocdn.net/14/dn/ZSfZPxO70E/DJNC0WsJym1OoiMmo8K5O1/o.jpg","secure_icon_image_url": "https://k.kakaocdn.net/14/dn/ZSfZPxO70E/DJNC0WsJym1OoiMmo8K5O1/o.jpg","user_management": "on","user_id": 1376016924429759243,"user_status": "REGISTERED","account_id": 2137162, //권한 필요"talk_user_id": 700119942 //권한 필요}
응답: 연결된 사용자, app_key와 owner_developer 요청
- 요청 시
results파라미터로app_key,owner_developer를 전달한 경우의 응답 예제입니다.
{"id": 977071,"name": "Sample","company": "SampleCompany","type": "KAKAO","status": "ACTIVE","category": "Book_Reference","phase": "NORMAL","owner_developer": {"id": 576952,"registered_at": "2020-02-17T06:43:02Z","deactivated": false,"account_id": 2137162},"user_id": 1376016924429759243,"user_status": "REGISTERED","account_id": 2137162, //권한 필요"talk_user_id": 700119942 //권한 필요}
응답: 연결되지 않은 사용자
- 연결 대기(PREREGISTERED) 상태인 사용자를 대상으로 요청한 경우의 응답 예제입니다.
{"id": 977071,"name": "Sample","company": "SampleCompany","type": "KAKAO","status": "ACTIVE","category": "Book_Reference","user_id": 1376016924429759243,"user_status": "PREREGISTERED","account_id": 2137162, //권한 필요"talk_user_id": 700119942 //권한 필요}
응답: 실패, 앱과 무관한 사용자
- 연결(REGISTERED), 연결 대기(PREREGISTERED) 상태가 아니며, 회원번호도 존재하지 않는 사용자를 대상으로 요청한 경우의 응답 예제입니다.
// HTTP/1.1 400 Bad Request{"msg": "NotRegisteredUserException","code": -101}
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 카카오http://kapi.kakao.com/v2/internal/user/history공동체 https://kapi.kakao.com/v2/internal/user/history | 액세스 토큰 서비스 앱 어드민 키 위임 |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| 필요: 공동체 앱 | 어드민 키 카카오 로그인 활성화 | 필요: 연결, 연결 대기, 연결 없음* | - |
사용자의 앱 연결 이력을 조회합니다. 이 API는 아래와 같은 용도로 사용할 수 있습니다.
- 사용자와 앱의 연결 상태 확인
- 사용자의 앱 최초 연결(서비스 첫 가입) 여부 확인 (
latest_deregistered_info필드 존재 여부로 판단 가능) - 서비스의 재가입 유예 정책 적용을 위한 사용자 연결 및 연결 해제 이력 확인
- 사용자와 연결 이력이 있는 앱의 기본 정보 조회
헤더에 원하는 인증 정보를 담아 GET으로 요청하고, 성공 시 앱 기본 정보와 사용자의 앱 연결 이력을 받습니다. 응답 중 카카오계정 ID(account_id)는 권한이 있는 앱에서 요청한 경우에만 응답에 포함됩니다.
참고: API 변경 사항
2021년 12월 28일부터 연결된 앱 연결 이력 조회 API가 새로운 버전으로 제공됩니다.
이 API는 샌드박스 페이즈에서만 샘플 앱으로 테스트 가능합니다.
샘플 앱 이외의 앱으로 테스트하려면 해당 앱에 필요한 권한을 받아야 합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 | O |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_id | String | 앱 연결 이력을 조회할 사용자 ID | O |
| target_id_type | String | target_id 타입, 아래 중 하나
| O |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
- 요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키:
target_app_key,target_id,target_id_type - 서비스 앱 ID:
target_app_id,target_id,target_id_type - 액세스 토큰:
target_access_token
- 서비스 앱 키:
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_app_key | String | 사용자의 앱 연결 이력을 조회할 서비스 앱의 키 | O(Optional) |
| target_app_id | Long | 사용자의 앱 연결 이력을 조회할 서비스 앱의 ID | O(Optional) |
| target_access_token | String | 앱 연결 이력을 조회할 사용자의 액세스 토큰 | O(Optional) |
| target_id | String | 앱 연결 이력을 조회할 사용자 ID | O |
| target_id_type | String | target_id 타입, 아래 중 하나
target_app_ids 파라미터 사용 시에는 account_id만 사용 가능 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| user_id | Long | 회원번호 연결 끊음( DEREGISTERED) 상태인 사용자인 경우 응답에 포함되지 않음참고: 사용자 ID 고정 시, 연결 해제 전후의 회원번호 동일 | X |
| account_id | Integer | 사용자의 카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유 | X |
| user_status | String | 사용자와 앱의 연결 상태, 아래 중 하나
| O |
| registered_at | Datetime | 사용자의 앱 연결 시각, UTC 현재 앱에 연결 상태일 때만 존재 (RFC3339 internet date/time 형식) | X |
| latest_deregistered_info | LatestDeregisteredInfo | 마지막 연결 해제 이력 앱과 최초 연결 또는 연결 대기 상태가 되어 연결 해제 이력이 없는 사용자의 경우 미존재 | X |
| app | App | 앱 정보 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| user_id | Long | 연결 해제 이전의 회원번호 참고: 사용자 ID 고정 시, 연결 해제 전후의 회원번호 동일 | O |
| deregistered_at | Datetime | 마지막 연결 해제 시각, UTC (RFC3339 internet date/time 형식) | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Integer | 앱 ID | O |
| name | String | 앱 이름 | O |
| company | String | 회사명(상호, 법인 또는 단체명) | O |
| type | String | 앱 타입, 아래 중 하나
참고: 카카오디벨로퍼스 앱 타입 | O |
| status | String | 앱 상태, 아래 중 하나
| O |
| category | String | 앱 카테고리 | O |
| app_key | String | 앱 키 앱 키로 요청 시, 해당 앱 키 앱 ID로 요청 시, 권한에 따라 대상 앱의 앱 키 제공(현재 REST API 키만 지원) 액세스 토큰으로 요청 시, 토큰 발급에 사용된 앱 키 | X |
| app_key_type | String | app_key의 타입, 아래 중 하나
| X |
| phase | String | 테스트 앱 여부, 아래 중 하나
| O |
요청: 액세스 토큰 방식
- 파라미터: 없음
curl -v -G GET "http://kapi.kakao.com/v2/internal/user/history" \-H "Authorization: Bearer ${ACCESS_TOKEN}"
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 카카오계정 ID(account_id)
- 사용자 ID(
curl -v -G GET "http://kapi.kakao.com/v2/internal/user/history" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id=200937" \-d "target_id_type=account_id"
요청: 위임 방식
- 파라미터
- 서비스 앱 키(
target_app_key) - 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 카카오톡 회원번호(talk_id)
- 서비스 앱 키(
curl -v -G GET "http://kapi.kakao.com/v2/internal/user/history" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_id=200937" \-d "target_id_type=talk_id" \-d "target_app_key=${SERVICE_APP_KEY}"
요청: 위임 방식
- 파라미터
- 서비스 앱 ID(
target_app_id) - 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 카카오계정 ID(account_id)
- 서비스 앱 ID(
curl -v -G GET "http://kapi.kakao.com/v2/internal/user/history" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_id=200937" \-d "target_id_type=account_id" \-d "target_app_id=276481"
요청: 위임 방식
- 파라미터
- 액세스 토큰(
target_access_token)
- 액세스 토큰(
curl -v -G GET "http://kapi.kakao.com/v2/internal/user/history" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_access_token=${ACCESS_TOKEN}"
응답: 처음 앱과 연결된 사용자
// HTTP/1.1 200 OK{"user_id": 142452,"account_id": 81825, // 카카오계정 ID 응답 권한 필요"user_status": "REGISTERED","registered_at": "2021-12-27T06:00:47Z","app": {"id": 208120,"name": "Sample","company": "SampleCompany","type": "KAKAO","status": "ACTIVE","category": "Book_Reference","app_key_type": "REST_API_KEY","app_key": "${REST_API_KEY}"}}
응답: 연결 해제한 사용자
// HTTP/1.1 200 OK{"account_id": 81825, // 카카오계정 ID 응답 권한 필요"user_status": "DEREGISTERED","latest_deregistered_info": {"user_id": 142452,"deregistered_at": "2021-12-27T06:03:51Z"},"app": {"id": 208120,"name": "Sample","company": "SampleCompany","type": "KAKAO","status": "ACTIVE","category": "Book_Reference","app_key_type": "ADMIN_KEY","app_key": "${APP_ADMIN_KEY}"}}
응답: 앱 연결 해제 후 다시 연결 대기(PREREGISTERED) 상태가 된 사용자
// HTTP/1.1 200 OK{"user_id": 142452,"account_id": 81825, // 카카오계정 ID 응답 권한 필요"user_status": "PREREGISTERED","latest_deregistered_info": {"user_id": 142452,"deregistered_at": "2021-12-27T06:08:49Z"},"app": {"id": 208120,"name": "Sample","company": "SampleCompany","type": "KAKAO","status": "ACTIVE","category": "Book_Reference","app_key_type": "ADMIN_KEY","app_key": "${APP_ADMIN_KEY}"}}
응답: 앱 연결 해제 후 다시 연결 상태가 된 사용자
// HTTP/1.1 200 OK{"user_id": 142452,"account_id": 81825, // 카카오계정 ID 응답 권한 필요"user_status": "REGISTERED","registered_at": "2021-12-27T06:06:52Z","latest_deregistered_info": {"user_id": 142452,"deregistered_at": "2021-12-27T06:03:51Z"},"app": {"id": 208120,"name": "Sample","company": "SampleCompany","type": "KAKAO","status": "ACTIVE","category": "Book_Reference","app_key_type": "ADMIN_KEY","app_key": "${APP_ADMIN_KEY}"}}
응답: 사용자 ID 고정을 비활성화한 앱, 앱 연결 해제 후 다시 연결 상태가 된 사용자
// HTTP/1.1 200 OK{"user_id": 1376016924427033581, // 사용자 ID 고정을 비활성화했으므로 기존과 다른 회원번호 사용"account_id": 371878, // 카카오계정 ID 응답 권한 필요"user_status": "REGISTERED","registered_at": "2015-12-24T08:27:13Z","latest_deregistered_info": {"user_id": 1376016924427033580,"deregistered_at": "2015-12-24T08:26:56Z"},"app": {"id": 238382,"name": "Sample","company": "SampleCompany","type": "KAKAO","status": "ACTIVE","category": "Book_Reference","app_key_type": "ADMIN_KEY","app_key": "${APP_ADMIN_KEY}"}}
응답: 회원번호만 존재하고 앱과 연결되지 않은 사용자
- 회원번호 사전 발급으로 회원번호만 발급받은 사용자, 해당 문서 참고
// HTTP/1.1 200 OK{"user_id": 1376016924428962250,"account_id": 371878, // 카카오계정 ID 응답 권한 필요"user_status": "NONE","latest_deregistered_info": {"user_id": 1376016924428962250,"deregistered_at": "2019-04-17T10:02:20Z"},"app": {"id": 837239,"name": "Sample","company": "SampleCompany","type": "DEFAULT","status": "ACTIVE","category": "Book_Reference"}}
응답: 앱 연결 또는 회원번호 발급 이력이 전혀 없는 사용자를 대상으로 요청한 경우
// HTTP/1.1 400 Bad Request{"msg": "This user have never signed up.","code": -101}
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 카카오http://kapi.kakao.com/v1/internal/user/status공동체 https://kapi.kakao.com/v1/internal/user/status | 액세스 토큰 서비스 앱 어드민 키 위임 |
사용자의 서비스 앱 연결 상태와 카카오계정 로그인 가능 여부를 조회합니다. 서비스 앱과 연결 또는 연결 대기 상태인 사용자의 카카오계정 로그인 가능 여부를 확인하는 용도로 사용합니다.
헤더에 원하는 인증 정보를 담아 GET으로 요청합니다. 요청 성공 시 사용자 ID와 연결 상태, 카카오계정 로그인 가능 여부 정보를 받습니다. 응답 중 카카오계정 ID(account_id)는 권한이 있는 앱에서 요청한 경우에만 응답에 포함됩니다.
카카오계정 로그인 가능 여부(login_available) 필드는 앱의 동의항목에 [카카오계정(이메일)] 또는 [카카오계정(전화번호)] 동의항목 중 하나라도 설정하고 사용자에게 동의받은 경우에만 응답에 포함됩니다. 해당 필드를 반드시 제공받아야 할 경우, 해당 동의항목 중 하나 이상을 [필수 동의] 동의항목으로 설정할 것을 권장합니다.
카카오계정 로그인 가능 여부(login_available) 필드는 사용자의 카카오계정이 카카오 로그인 가능한 상태인지를 나타냅니다. 카카오 로그인은 정상적인 인증 상태인 카카오계정에만 로그인 및 토큰 발급을 허용합니다. 카카오계정에 인증 관련 문제가 없는 이메일 또는 전화번호 정보가 하나라도 존재한다면 정상적인 인증 상태입니다.(참고: 카카오계정 유형/상태) 일반적인 인증 관련 문제는 아래와 같습니다.
- 사용자 카카오계정 이메일이 만료된 경우
- 사용자 전화번호로 다른 사용자가 인증해 인증 뺏김 상태가 된 경우
서비스의 특정 기능을 정상적인 인증 상태인 카카오계정 사용자에 한해 제공해야 할 경우, 해당 기능 제공 전 카카오계정의 상태를 확인하는 용도로 login_available 필드를 사용할 수 있습니다. login_available 필드의 값이 false인 카카오계정은 카카오 로그인으로 토큰을 발급받을 수 없고, 기존 액세스 토큰의 갱신도 불가능합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 | O |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_id | String | target_id_type에 해당하는 사용자 ID | O |
| target_id_type | String | target_id 타입, 아래 중 하나
| O |
- 내부 API 요청 시에만 사용 가능합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
- 요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키:
target_app_key,target_id,target_id_type - 서비스 앱 ID:
target_app_id,target_id,target_id_type - 액세스 토큰:
target_access_token
- 서비스 앱 키:
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_app_key | String | 카카오계정 상태를 확인할 서비스 앱의 키 | O(Optional) |
| target_app_id | Long | 카카오계정 상태를 확인할 서비스 앱의 ID | O(Optional) |
| target_access_token | String | 카카오계정 상태를 확인할 사용자의 액세스 토큰 값 | O(Optional) |
| target_id | String | 카카오계정 상태를 확인할 사용자 ID | O(Optional) |
| target_id_type | String | target_id 타입, 아래 중 하나
| O(Optional) |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Long | 회원번호 | O |
| account_id Permission | Long | 카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유 | X |
| user_status | String | 사용자의 앱 연결 상태, 아래 중 하나
| O |
| login_available | Boolean | 카카오계정 로그인 가능 여부 필요한 동의항목: 카카오계정(전화번호) 또는 카카오계정(이메일) | X |
| is_spam_user Permission | Boolean | 카카오계정의 스팸 의심 상태 여부 넓은 범위의 의심 상태로 해당 값에 대한 별도 처리 대신 참고 정보로 사용 권장 제공 조건: 카카오계정 스팸 의심 상태 여부 응답 권한 보유 | X |
| is_dormant_user Permission | Boolean | 카카오계정의 휴면 상태 여부 제공 조건: 카카오계정 휴면 상태 여부 응답 권한 보유 | X |
| is_blocked_user Permission | Boolean | 카카오계정의 제재 상태 여부 제공 조건: 카카오계정 제재 상태 여부 응답 권한 보유 | X |
요청: 액세스 토큰 방식
- 파라미터: 없음
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/status" \-H "Authorization: Bearer ${ACCESS_TOKEN}"
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 회원번호(user_id)
- 사용자 ID(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/status" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id=2131762" \-d "target_id_type=user_id"
요청: 위임 방식
- 파라미터
- 서비스 앱 키(
target_app_key) - 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 회원번호(user_id)
- 서비스 앱 키(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/status" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_app_key=${SERVICE_APP_KEY}" \-d "target_id_type=user_id" \-d "target_id=1376016924426542768"
요청: 위임 방식
- 파라미터
- 서비스 앱 ID(
target_app_id) - 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 회원번호(user_id)
- 서비스 앱 ID(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/status" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_app_id=57669" \-d "target_id_type=user_id" \-d "target_id=1376016924426542768"
요청: 위임 방식
- 파라미터
- 액세스 토큰(
target_access_token)
- 액세스 토큰(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/status" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_access_token=${ACCESS_TOKEN}"
응답
// HTTP/1.1 200 OK{"id": 1376016924429759423,"account_id": 2131762, // 카카오계정 ID 응답 권한 필요"user_status": "REGISTERED", // REGISTERED, PREREGISTERED 중 하나"login_available": true, // 카카오계정(이메일), 카카오계정(전화번호) 동의항목 필요"is_spam_user": false, // 카카오계정 스팸 의심 상태 여부 응답 권한 필요"is_dormant_user": false, // 카카오계정 휴면 상태 여부 응답 권한 필요"is_blocked_user": false // 카카오계정 제재 상태 여부 응답 권한 필요}
응답: 모든 응답 권한 미보유
// HTTP/1.1 200 OK{"id": 1376016924429759423,"user_status": "REGISTERED" // REGISTERED, PREREGISTERED 중 하나}
응답: 카카오계정 ID와 카카오계정 로그인 가능 여부 미포함
- 카카오계정 ID 응답 권한이 없어
account_id필드가 응답에 포함되지 않음 - 필요한 동의항목이 설정되어 있지 않거나 사용자가 동의하지 않아
login_available필드가 응답에 포함되지 않음
// HTTP/1.1 200 OK{"id": 1376016924430619323,"user_status": "REGISTERED","is_spam_user": false, // 카카오계정 스팸 의심 상태 여부 응답 권한 필요"is_dormant_user": false, // 카카오계정 휴면 상태 여부 응답 권한 필요"is_blocked_user": false // 카카오계정 제재 상태 여부 응답 권한 필요}
응답: 실패, 앱과 연결되지 않은 사용자
// HTTP/1.1 400 Bad Request{"msg": "NotRegisteredUserException","code": -101}
응답: 실패, 존재하지 않는 사용자
// HTTP/1.1 400 BadRequest{"msg": "NotExistKakaoAccountException","code": -103}
응답: 실패, 휴면 상태인 사용자
- 카카오계정 휴면 상태 여부 응답 권한을 보유한 경우
is_dormant_user필드 값true로 응답
// HTTP/1.1 400 BadRequest{"msg": "the account is inactive.","code": -103}
응답: 실패, 제재 또는 보호조치 된 사용자
- 카카오계정 제재 상태 여부 응답 권한을 보유한 경우
is_blocked_user필드 값true로 응답
// HTTP/1.1 403 Forbidden{"msg": "the account is blocked.","code": -4,"blocked_id": "853205", // 카카오계정 ID 응답 권한 필요"block_type": "account" // 카카오계정 ID 응답 권한 필요}
응답: 실패, 기타 서버 에러
// HTTP/1.1 400 BadRequest{"msg": "InternalErrorException","code": -1}
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 카카오http://kapi.kakao.com/v1/internal/user/search공동체 https://kapi.kakao.com/v1/internal/user/search | 서비스 앱 어드민 키 |
target_id_type | 동의항목 | 동의항목 설정 권한 정보 |
|---|---|---|
| EMAIL(이메일) | 카카오계정(이메일) | 선택 동의 설정 권한 기본 제공 필수 동의 설정 권한이 필요할 경우 인하우스 앱 등록 또는 권한 신청 |
| PHONE_NUMBER(전화번호) | 카카오계정(전화번호) | 기본 제공하지 않음 동의항목 설정 권한을 받으려면 인하우스 앱 등록 또는 권한 신청 필요 |
사용자의 이메일 또는 전화번호에 해당하는 카카오계정 ID를 조회합니다. CS(고객지원, Customer Service) 처리 시 문의한 고객 정보로 카카오계정 ID를 조회하는 용도로 사용 가능합니다.
서비스 앱 어드민 키를 헤더에 담아 GET으로 요청합니다. target_id_type 값에 해당하는 동의항목이 앱에 설정되어 있고, 사용자가 동의한 상태여야만 카카오계정 ID를 조회할 수 있습니다.
요청 성공 시 응답은 사용자의 카카오계정 ID(account_id)와 회원번호(user_id), 앱 연결 상태(user_status)를 포함합니다. 카카오계정 ID는 권한이 있어야만 응답에 포함됩니다.
요청이 실패한 경우, 에러 코드로 원인을 확인합니다. 이메일, 전화번호로 조회한 카카오계정이 휴면이거나 제재 상태인 경우에는 에러 응답을 받습니다. 제재 상태인 경우, 카카오계정 ID 응답 권한이 있을 경우 에러 응답에 카카오계정 ID가 포함됩니다.
다른 사용자 정보가 필요할 경우, 응답으로 받은 카카오계정 ID 또는 회원번호로 사용자 정보 조회를 요청해 제공 받을 수 있습니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_id | String | 카카오계정 ID를 조회할 사용자의 카카오계정 이메일 또는 전화번호 한국 번호인 경우 821012345678나 +82 10-1234-5678로 요청(참고: libphonenumber) | O |
| target_id_type | String | target_id의 타입, EMAIL(이메일) 또는 PHONE_NUMBER(전화번호) | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Long | 회원번호 | O |
| account_id | Integer | 카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유 | X |
| user_status | String | 사용자의 앱 연결 상태, 아래 중 하나
| O |
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 이메일(EMAIL)
- 사용자 ID(
curl -v --get "http://kapi.kakao.com/v1/internal/user/search" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id=platform.developers@kakaocorp.com" \-d "target_id_type=EMAIL"
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 사용자 ID(
target_id):+82 10-1234-5678형식의 전화번호 - 사용자 ID 타입(
target_id_type): 전화번호(PHONE_NUMBER)
- 사용자 ID(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/search" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id=+82 10-1234-5678" \-d "target_id_type=PHONE_NUMBER"
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 사용자 ID(
target_id):821012345678형식의 전화번호 - 사용자 ID 타입(
target_id_type): 전화번호(PHONE_NUMBER)
- 사용자 ID(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/search" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id=821012345678" \-d "target_id_type=PHONE_NUMBER"
응답
{"id": 1234567890,"account_id": 371878, // 권한 필요"user_status": "REGISTERED"}
응답: 실패, 필요한 동의항목 설정의 권한 없음
// HTTP/1.1 403 Forbidden{"msg": "permission denied","code": -5}
응답: 실패, 사용자가 필요한 동의항목에 동의하지 않음
// HTTP/1.1 403 Forbidden{"msg": "insufficient scopes.","code": -402,"api_type": null,"required_scopes": ["phone_number"],"allowed_scopes": ["birthday", "talk_message", "gender", "profile", "friends", "age_range", "account_email"]}
응답: 실패, 앱에 필요한 동의항목이 설정되지 않음
// HTTP/1.1 403 Forbidden{"code": -3,"msg": "[application(id=575003, name='Sample')] App disabled [phone_number] scopes for this API on developers.kakao.com. Enable it first."}
응답: 실패, 사용자 제재 상태
// HTTP/1.1 403 Forbidden{"msg": "the account is blocked.","code": -4}
응답: 실패, 사용자 제재 상태, 카카오계정 ID 응답 권한 있음
// HTTP/1.1 403 Forbidden{"msg": "the account is blocked.","code": -4,"blocked_id": "853205", // account_id 권한 필요, 제재된 카카오계정의 ID"block_type": "account" // account_id 권한 필요, blocked_id의 타입}
응답: 실패, 이메일로 조회되는 계정이 없는 경우 (휴면 계정 포함)
// HTTP/1.1 400 BadRequest{"msg": "the kakao account which associated with this email does not exist","code": -103}
응답: 실패, 전화번호로 조회되는 계정이 없는 경우 (휴면 계정 포함)
// HTTP/1.1 400 BadRequest{"msg": "the kakao account which associated with this phoneNumber does not exist","code": -103}
응답: 실패, 이메일 또는 전화번호로 조회되는 계정이 앱에 연결하지 않은 경우
// HTTP/1.1 400 BadRequest{"msg": "NotRegisteredUserException","code": -101}
| 메서드 | URL | 인증 방식 |
|---|---|---|
POST | 카카오http://kapi.kakao.com/v1/internal/user/touch_account공동체 https://kapi.kakao.com/v1/internal/user/touch_account | 액세스 토큰 서비스 앱 어드민 키 |
사용자 카카오계정의 최종 접속 시간을 갱신해 휴면 상태로 전환되지 않게 합니다.
사용자가 카카오 로그인으로 서비스 앱과 연결된 후, 로그인 등 서비스 진입 과정 없이 백그라운드(Background)에서 서비스 기능을 사용하는 경우가 있습니다. 이러한 경우에 사용자의 카카오계정 휴면 전환으로 인한 문제가 발생하지 않도록 앱에 연결된 카카오계정 휴면 방지 API를 사용합니다.(예: 카카오페이 오프라인 결제, 예약 송금, 자동 결제 등)
헤더에 원하는 인증 정보를 담아 POST로 요청합니다. 앱과 연결된 사용자를 대상으로만 호출할 수 있으며, 대상 사용자의 카카오계정이 휴면, 제재, 보호조치 상태가 아니어야 합니다. 요청 성공 시 사용자의 회원번호와 카카오계정 상태를 받습니다. 권한이 있는 경우 카카오계정 ID를 함께 제공합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 | O |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_id | String | target_id_type에 해당하는 사용자 ID | O |
| target_id_type | String | 아래 중 하나
| X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Long | 회원번호 | O |
| account_id | Integer | 카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유 | X |
| user_status | String | 앱과 사용자의 연결 상태, REGISTERED로 고정참고: 앱에 연결된 카카오계정 휴면 방지 API는 앱과 연결된 사용자를 대상으로만 호출 가능하므로 REGISTERED 외 값을 반환하지 않음 | O |
요청: 액세스 토큰 방식
- 파라미터: 없음
curl -v POST "http://kapi.kakao.com/v1/internal/user/touch_account" \-H "Authorization: Bearer ${ACCESS_TOKEN}"
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type):
- 사용자 ID(
curl -v POST "http://kapi.kakao.com/v1/internal/user/touch_account" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id_type=account_id" \-d "target_id=200937"
응답
// HTTP/1.1 200 OK{"id": 1376016924429759243,"account_id": 2137162, // 카카오계정 ID 응답 권한 필요"user_status": "REGISTERED"}
응답: 실패, 앱과 연결되지 않은 사용자
// HTTP/1.1 400 Bad Request{"msg": "NotRegisteredUserException","code": -101}
응답: 실패, 존재하지 않는 사용자
// HTTP/1.1 400 BadRequest{"msg": "NotExistKakaoAccountException","code": -103}
응답: 실패, 휴면 상태인 사용자
// HTTP/1.1 400 BadRequest{"msg": "the account is inactive.","code": -103}
응답: 실패, 제재 또는 보호조치 된 사용자
// HTTP/1.1 403 Forbidden{"msg": "the account is blocked.","code": -4,"blocked_id": "853205", // 카카오계정 ID 응답 권한 필요"block_type": "account" // 카카오계정 ID 응답 권한 필요}
응답: 실패, 기타 서버 에러
// HTTP/1.1 400 BadRequest{"msg": "InternalErrorException","code": -1}
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 카카오http://kapi.kakao.com/v2/internal/user/authenticate공동체 https://kapi.kakao.com/v2/internal/user/authenticate | 위임 |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| 필요 | 어드민 키 카카오 로그인 활성화 | 필요: 연결, 연결 대기, 연결 없음 | - |
액세스 토큰과 앱 키에 해당하는 앱이 일치하는지 확인합니다. 플랫폼 앱이 각 서비스 앱의 사용자 액세스 토큰과 앱 키로 앱을 확인 및 인증하는 용도로 사용합니다. 액세스 토큰에 해당하는 앱 키와 요청 시 전달된 앱 키의 타입이 일치하는지는 확인하지 않습니다. 이 API를 사용하려면 권한이 필요합니다.
헤더에 플랫폼 앱 어드민 키를 담아 GET으로 요청합니다. target_kakao_agent에 KA 헤더 인증을 위한 서비스의 요청 환경 정보를 전달해야 하며, 전달된 값을 서비스 앱 정보와 비교해 올바른 요청인지 인증합니다. 이 API는 기본적으로 연결 상태인 사용자 대상으로만 호출 가능하지만, 비로그인 서비스의 경우 account_id를 사용해 연결 상태와 관계 없이 호출할 수 있습니다.
요청 성공 시 응답은 사용자 액세스 토큰과 앱 키에 해당하는 앱의 정보를 포함합니다. 인증 실패 시 에러로 응답하며 결과를 extras.detail_cause에 안내합니다.
- 내부 API 요청 시에만 사용 가능합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
- 요청 대상 사용자를 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
- 서비스 앱 키:
target_app_key,target_id,target_id_type,target_kakao_agent - 액세스 토큰:
target_access_token,target_app_key,target_kakao_agent - 비로그인 서비스:
target_app_key,account_id,target_kakao_agent
- 서비스 앱 키:
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_app_key | String | 서비스 앱의 키 JavaScript 키 또는 네이티브 앱 키만 사용 가능 | O(Optional) |
| target_id | String | 사용자 ID | O(Optional) |
| target_id_type | String | target_id 타입, 아래 중 하나
| O(Optional) |
| target_access_token | String | 서비스 앱의 사용자 액세스 토큰 | O(Optional) |
| account_id | Integer | 카카오계정 ID | O(Optional) |
| target_kakao_agent | String | 서비스로부터 전달받은 KA 헤더 액세스 토큰 발급 시 사용된 앱 키 타입에 따라 아래 정보를 반드시 포함해야 함 네이티브 앱 키: os, originREST API 키: ipJavaScript 키: os, origin | O |
| results | String | 앱의 추가 정보 요청, 아래 값 사용app_platform: 플랫폼 정보 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| app_info | AppInfo | 앱 정보 | O |
| user_id | Long | 사용자의 회원번호 제공 조건: 사용자가 앱에 연결 또는 연결 대기 상태인 경우 중요: target_id, target_id_type을 사용해 account_id로 요청한 경우 제공하지 않음 | X |
| account_id | Integer | 사용자의 카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유 | X |
| talk_user_id | Long | 사용자의 카카오톡 회원번호 제공 조건: 카카오톡 회원번호(talk_id) 응답 권한 보유 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Integer | 앱 ID | O |
| name | String | 앱 이름 | O |
| company | String | 회사명 | O |
| type | String | 앱 타입 | O |
| category | String | 앱 카테고리 | O |
| secure_icon_image_url | String | 앱 아이콘 이미지 URL | O |
| app_key | String | 요청 시 사용한 앱 키 | O |
| app_key_type | String | 요청 시 사용한 앱 키 타입 | O |
| execution_url | ExecutionUrl[] | OS별 앱 실행 커스텀 URL 제공 조건: 요청 시 results 파라미터에 app_platform을 포함한 경우 | X |
| market_url | MarketUrl[] | OS별 앱 설치 커스텀 URL 제공 조건: 요청 시 results 파라미터에 app_platform을 포함한 경우 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| platform | String | 플랫폼 정보, 아래 중 하나
| O |
| pkgnames | String[] | platform이 android인 경우, 앱에 설정된 안드로이드 패키지 이름(Package name) 목록 | X |
| urls | String[] | platform이 iOS나 iPad인 경우, 앱에 설정된 커스텀 URL 스킴platform이 web인 경우, 앱에 설정된 도메인 웹 목록 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| platform | String | 플랫폼 정보, 아래 중 하나
| O |
| urls | String[] | 앱 설치 URL 목록 | X |
- 인증 실패 시 에러 응답의
extras및 하위 필드에 결과 안내
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| detail_cause | String | 인증 실패 원인, 아래 중 하나
| O |
요청: 위임 방식
- 파라미터
- 서비스 앱의 사용자 액세스 토큰(
target_access_token) - 서비스 앱의 앱 키(
target_app_key): JavaScript 키 - 서비스로부터 전달받은 KA 헤더(
target_kakao_agent): sdk, os, lang, device, origin - 요청할 앱 정보(
results): 앱의 플랫폼 정보(app_platform)
- 서비스 앱의 사용자 액세스 토큰(
curl -v -G GET "http://kapi.kakao.com/v2/internal/user/authenticate" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_access_token=${ACCESS_TOKEN}" \-d "target_app_key=${SERVICE_APP_KEY}" \-d "results=app_platform" \--data-urlencode "target_kakao_agent=sdk/1.0.22 os/javascript lang/en-GB device/Linux_armv7l origin/http%3A%2F%2Fwww.nytimes.com"
요청: 위임 방식
- 파라미터
- 서비스 앱의 앱 키(
target_app_key): 네이티브 앱 키 - 사용자 ID
- 사용자 ID 타입(
user_id) - 서비스로부터 전달받은 KA 헤더(
target_kakao_agent): sdk, sdk_type, os, lang, origin, android_pkg
- 서비스 앱의 앱 키(
curl -v -G GET "http://kapi.kakao.com/v2/internal/user/authenticate" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_app_key=${SERVICE_APP_KEY}" \-d "target_id=1376016924429759243" \-d "target_id_type=user_id" \--data-urlencode "target_kakao_agent=sdk/1.0.47 sdk_type/kotlin os/android-19 lang/ko-KR device/LG-F240S origin/Qm7e1b/eHr14u31lGLoJX8oR5NE= android_pkg/com.kakao.sample"
요청: 위임 방식
- 파라미터
- 서비스 앱의 앱 키(
target_app_key): JavaScript 키 - 카카오계정 ID(
account_id) - 서비스로부터 전달받은 KA 헤더(
target_kakao_agent): sdk, os, lang, device, origin
- 서비스 앱의 앱 키(
curl -v -G GET "http://kapi.kakao.com/v2/internal/user/authenticate" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_app_key=${SERVICE_APP_KEY}" \-d "account_id=2137162" \--data-urlencode "target_kakao_agent=sdk/1.0.22 os/javascript lang/en-GB device/Linux_armv7l origin/http%3A%2F%2Fdevelopers.kakao.com"
응답
// HTTP/1.1 200 OK{"app_info": {"id": 977071,"name": "Sample","company": "SampleCompany","type": "KAKAO","category": "None","secure_icon_image_url": "https://k.kakaocdn.net/14/dn/ZSfZPxO70E/DJNC0WsJym1OoiMmo8K5O1/o.jpg","app_key": "${SERVICE_APP_KEY}","app_key_type": "NATIVE_APP_KEY","execution_url": [{"platform": "android","pkgnames": ["com.kakao.main", "com.kakao.dev", "com.kakao.partner"]},{"platform": "iOS","urls": ["kakaoc6987e556ecb125060cd7cf92d298745://", "kakaoc6987e556ecb125060cd7cf92d298745-com.kakao.dev://", "kakaoc6987e556ecb125060cd7cf92d298745-com.kakao.partner://"]},{"platform": "web","urls": ["http://basicdomain.com", "http://2nddomain.com"]}],"market_url": [{"platform": "android","urls": ["market://details?id=com.kakao.main", "market://details?id=com.kakao.dev", "market://details?id=com.kakao.partner"]},{"platform": "iOS","urls": ["https://itunes.apple.com/app/id0", "https://itunes.apple.com/app/id1", "https://itunes.apple.com/app/id2"]}]},"user_id": 1376016924429759243,"account_id": 2137162,"talk_user_id": 700119942}
응답: 비로그인 서비스에서 요청한 경우
// HTTP/1.1 200 OK{"app_info": {"id": 977071,"name": "Sample","company": "SampleCompany","type": "KAKAO","category": "None","secure_icon_image_url": "https://k.kakaocdn.net/14/dn/ZSfZPxO70E/DJNC0WsJym1OoiMmo8K5O1/o.jpg","app_key": "a3a96b181d791d8448b2c7ad747660aa","app_key_type": "JAVASCRIPT_KEY"},"account_id": 2137162,"talk_user_id": 700119942}
응답: 액세스 토큰과 앱 키에 해당하는 앱 불일치
// HTTP/1.1 401 Unauthorized{"msg": "mismatched application information.","code": -401,"extras": {"detail_cause": "INVALID_TOKEN"}}
응답: 앱 키가 올바르지 않음
// HTTP/1.1 401 Unauthorized{"msg": "appKey(e27c37c5833e6ffc45b37385d4d53d0f) does not exist","code": -401,"extras": {"detail_cause": "INVALID_APP_KEY"}}
응답: KA 헤더 인증 실패
// HTTP/1.1 401 Unauthorized{"msg": "mismatched! (inputAppKeyType = NATIVE_APP_KEY, inputOsType = IOS), (expectedOrigin = [${BUNDLE_ID}], inputOrigin = com.kakao.sample)","code": -401,"extras": {"detail_cause": "INVALID_PLATFORM"}}
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 카카오http://kapi.kakao.com/v1/internal/user/preregister공동체 https://kapi.kakao.com/v1/internal/user/preregister | 위임 |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| 필요 | 어드민 키 카카오 로그인 활성화 | 필요: 연결, 연결 대기, 연결 없음 | - |
회원번호 사전 발급은 앱에 미연결(None) 상태의 사용자 회원번호를 생성합니다. 미연결 상태의 사용자는 회원번호 외 어떤 정보도 가지고 있지 않습니다.
헤더에 원하는 인증 정보를 담아 GET으로 요청하고, 성공 시 사용자의 회원번호를 받습니다.
| 이름 | 형식 | 설명 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_app_id | Long | 서비스 앱 ID | O |
| target_id | String | target_id_type에 해당하는 사용자 ID | O |
| target_id_type | String | 아래 중 하나
| X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | String | 서비스의 회원번호(app_user_id) | O |
| status | String | 사용자 상태, 아래 중 하나
참고: PREREGISTERED, CHECK_AGE_AUTH 상태는 회원번호를 사용하는 앱에만 존재 | O |
요청
- 파라미터
- 서비스 앱 ID(
target_app_id) - 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 카카오계정 ID(account_id)
- 서비스 앱 ID(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/preregister" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_app_id=12364" \-d "target_id_type=account_id" \-d "target_id=200937"
응답
{"id": "19394910394200111937","status": "PREREGISTERED"}
사용처 제한 API는 지정된 사용처에만 제공하는 카카오 API입니다. 지정된 사용처 이외의 서비스에서 사용처 제한 API를 사용하려면 [서비스] API플랫폼 아지트에서 별도 협의가 필요합니다.
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 카카오http://kapi.kakao.com/v2/internal/user/demographics공동체 https://kapi.kakao.com/v2/internal/user/demographics배치 http://kapi.kakao.com/v2/internal/user/demographics/batch | 액세스 토큰 서비스 앱 어드민 키 |
- 아래 동의항목은 API 사용 권한이 있는 경우에만 설정 가능
- 데이터프로덕트전략팀과 사전 협의 후, KAPI 권한 신청을 참고해 동의항목 및 API 사용 권한 신청
- 데이터 사용 목적에 따라 [서비스 이용내역으로 추정한 정보] 동의항목의 설정 권한 부여
| 분석 데이터 | 동의항목 |
|---|---|
| 추정 연령대 추정 성별 | 서비스 이용내역으로 추정한 정보(연령대,성별)¹⁾ |
| 추정 관심사 | 서비스 이용내역으로 추정한 정보(관심사)¹⁾²⁾ |
사용자의 카카오 플랫폼 내 서비스 이용내역을 분석해 추정한 성별, 연령대, 관심사 정보를 받습니다. 이 API는 공동체 전용으로 필요한 동의항목을 참고해 권한을 받아야 사용할 수 있습니다. 카카오 서비스의 경우, Data Universe에서 필요한 데이터를 제공받을 수 있습니다. (참고: 카카오크루: 데이터 신청/제공, 카카오공동체크루: 데이터 신청/제공)
이 API는 연결 완료(REGISTERED)된 사용자를 대상으로만 호출할 수 있습니다. 각 분석 데이터의 필요한 동의항목을 설정하고, 사용자가 각 항목에 동의한 경우에 한해 응답에 정보가 포함됩니다.
원하는 인증 정보를 헤더에 담아 GET으로 요청하고, 성공 시 사용자의 분석 데이터를 받습니다. 관심사는 카테고리 형태로 제공하며, 자세한 카테고리 정보는 User Finding Operation을 참고합니다.
알파(Alpha)와 샌드박스(Sandbox) 페이즈(Phase)에서는 실제 데이터가 없어 모의 데이터(Mock data) 응답을 제공하고, 베타(Beta)와 프로덕션(Production) 페이즈에서만 실제 사용 가능한 데이터로 응답을 제공하는 점에 유의합니다.
응답 중 카카오계정 ID(account_id)는 권한이 있는 앱에서 내부 API로 요청한 경우에만 응답에 포함됩니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 | O |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_id | String | 분석 데이터를 가져올 사용자 ID | O |
| target_id_type | String | target_id 타입, 아래 중 하나
| O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Long | 사용자 회원번호(user_id) | O |
| account_id | Integer | 사용자의 카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유 | X |
| age_group | AgeGroupInfo | 추정 연령대 필요한 동의항목: 서비스 이용내역으로 추정한 정보(연령대,성별) | X |
| gender | String | 추정 성별female: 여성male: 남성필요한 동의항목: 서비스 이용내역으로 추정한 정보(연령대,성별) | X |
| interests | InterestInfo[] | 추정 관심사 필요한 동의항목: 서비스 이용내역으로 추정한 정보(관심사) | X |
| 이름 | 타입 | 설명 |
|---|---|---|
| 10_year_age_band | Integer | 10세 단위 연령대
|
| 5_year_age_band | Integer | 5세 단위 연령대
|
| 이름 | 타입 | 설명 |
|---|---|---|
| full_category_id | String | 관심사 카테고리 ID |
| full_category_name | String | full_category_id와 하위 단계 카테고리 이름으로 구성된 관심사 카테고리 정보 |
| simple_category_id | String | full_category_id의 가장 상위 단계인 depth1의 카테고리 ID |
| simple_category_name | String | simple_category_id와 해당 카테고리 이름으로 구성된 가장 상위 관심사 카테고리 정보 |
| score | Double | 관심도 수치(최소: 0, 최대: 1) |
| extra_scores | Map<String, Double> | 관심사를 다각도로 분석해볼 수 있도록 기본 관심도 수치(score) 외에 제공하는 추가 관심도 수치 |
| depth | DepthInfo | 관심사 카테고리의 단계 구분(depth) 상세 정보 |
| 이름 | 타입 | 설명 |
|---|---|---|
| count | Integer | 관심사 카테고리의 총 단계 구분(depth) 수 |
| depth1_category_name | String | depth1의 카테고리명 |
요청: 액세스 토큰 방식
- 파라미터: 없음
curl -v -G GET "http://kapi.kakao.com/v2/internal/user/demographics" \-H "Authorization: Bearer ${ACCESS_TOKEN}"
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 카카오계정 ID(account_id)
- 사용자 ID(
curl -v -G GET "http://kapi.kakao.com/v2/internal/user/demographics" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id=200937" \-d "target_id_type=account_id"
응답
{"id": 12345667,"account_id": 3464575,"age_group": {"10_year_age_band": 20,"5_year_age_band": 20},"gender": "female","interests": [{"full_category_id": "I320101","full_category_name": "I320101-비즈니스/경제-금융-재테크","simple_category_id": "I32","simple_category_name": "I32-비즈니스/경제","score": 0.5,"depth": {"count": 1,"depth1_category_name": "비즈니스/경제"}}// ...]}
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 카카오http://kapi.kakao.com/v1/internal/user/precheck/auth_info공동체 https://kapi.kakao.com/v1/internal/user/precheck/auth_info | 액세스 토큰 서비스 앱 어드민 키 |
요청 시 전달한 서비스의 본인인증 정보가 카카오계정에 등록 가능한 값인지 확인합니다. 이 API는 공동체 전용으로 카카오계정파트와 협의 후 권한을 받아야 사용할 수 있습니다.
헤더에 원하는 인증 방식별 정보를 담아 GET으로 요청합니다. 요청 시 전달된 사용자의 CI(연계정보)와 생년월일이 카카오계정의 본인인증 정보와 일치할 경우 성공 응답을 받습니다. 카카오계정에 본인인증 정보가 없는 경우에도 성공 응답이 반환됩니다.
요청 성공 시 응답은 본인인증 정보 등록 가능 여부(is_registrable)를 반환합니다. 응답 값이 true인 경우에만 공동체 앱: 카카오계정에 본인인증 정보 등록로 카카오계정에 서비스의 본인인증 정보를 등록할 수 있습니다.
참고: API 변경 사항
본인인증 정보 등록 가능 여부 조회는 2022년 3월 8일부터 새로운 버전으로 제공합니다. 신규 버전은 API의 용도를 보다 직관적으로 이해하고 사용할 수 있도록 변경되었습니다. 기존 버전인 /v1/internal/user/verify/auth_info의 정보는 링크에서 확인할 수 있습니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| ci | String | 서비스에서 자체 본인인증으로 획득한 사용자의 CI | O |
| birth_date | String | 사용자의 생년월일, YYYYMMDD 형식 | O |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_id | String | 사용자 ID | O |
| target_id_type | String | target_id 타입user_id: 회원번호account_id: 카카오계정 IDtalk_id: 카카오톡 회원번호 | O |
| ci | String | 서비스에서 자체 본인인증으로 획득한 사용자의 CI | O |
| birth_date | String | 사용자의 생년월일, YYYYMMDD 형식 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Long | 회원번호 | O |
| account_id | Integer | 카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유 | X |
| is_registrable | Boolean | 본인인증 정보 등록 가능 여부
| O |
요청: 액세스 토큰 방식
- 파라미터
- CI(
ci) - 생년월일(
birth_date)
- CI(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/precheck/auth_info" \-H "Authorization: Bearer ${ACCESS_TOKEN}" \--data-urlencode "ci=${CI}" \--data-urlencode "birth_date=20000101"
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 카카오계정 ID(account_id) - CI(
ci) - 생년월일(
birth_date)
- 사용자 ID(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/precheck/auth_info" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id=123465" \-d "target_id_type=account_id" \--data-urlencode "ci=${CI}" \--data-urlencode "birth_date=20000101"
응답: 본인인증 정보 등록 가능
// HTTP/1.1 200 OK{"id": 1376016924429358784,"account_id": 2137160, // 카카오계정 ID 응답 권한 필요"is_registable": true}
응답: 본인인증 정보 등록 불가
// HTTP/1.1 200 OK{"id": 1376016924429358784,"account_id": 2137160, // 카카오계정 ID 응답 권한 필요"is_registable": false}
| 메서드 | URL | 인증 방식 |
|---|---|---|
POST | 카카오http://kapi.kakao.com/v1/internal/user/register/auth_info공동체 https://kapi.kakao.com/v1/internal/user/register/auth_info | 액세스 토큰 서비스 앱 어드민 키 |
사용자 카카오계정에 서비스에서 자체 수집한 본인인증 정보를 등록합니다. 이 API는 공동체 전용으로 카카오계정파트와 협의 후 권한을 받아야 사용할 수 있습니다.
헤더에 원하는 인증 방식별 정보를 담아 POST로 요청합니다. 요청 시 카카오계정에 등록할 CI(연계정보)와 생년월일, 인증 유형을 모두 전달해야 합니다.
요청 성공 시 본인인증 정보 등록 완료 여부(registered)를 반환합니다. 응답 값이 false로 등록 실패인 경우, 공동체 앱: 본인인증 정보 등록 가능 여부 조회로 등록 가능 여부를 재확인해야 합니다.
참고: API 변경 사항
카카오계정에 본인인증 정보 등록은 2022년 3월 8일부터 새로운 버전으로 제공합니다. 신규 버전은 API의 용도를 보다 직관적으로 이해하고 사용할 수 있도록 변경되었습니다. 기존 버전인 /v1/internal/user/collect/auth_info의 정보는 링크에서 확인할 수 있습니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| ci | String | 서비스에서 자체 본인인증으로 획득한 사용자의 CI | O |
| birth_date | String | 사용자의 생년월일, YYYYMMDD 형식 | O |
| auth_type | String | 인증 유형, 본인인증기관 및 본인인증방식, 아래 중 하나
| O |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_id | String | 사용자 ID | O |
| target_id_type | String | target_id 타입user_id: 회원번호account_id: 카카오계정 IDtalk_id: 카카오톡 회원번호 | O |
| ci | String | 서비스에서 자체 본인인증으로 획득한 사용자의 CI | O |
| birth_date | String | 사용자의 생년월일, YYYYMMDD 형식 | O |
| auth_type | String | 인증 유형, 본인인증기관 및 본인인증방식, 아래 중 하나
| O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Long | 회원번호 | O |
| account_id | Integer | 카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유 | X |
| registered | Boolean | 본인인증 정보 등록 완료 여부
참고: 본인인증 정보 등록에 실패한 경우 false 값이 아닌 -410 에러 응답 반환 | O |
요청: 액세스 토큰 방식
- 파라미터
- CI(
ci) - 생년월일(
birth_date) - 인증기관 및 타입(
auth_type)
- CI(
curl -v POST "http://kapi.kakao.com/v1/internal/user/register/auth_info" \-H "Authorization: Bearer ${ACCESS_TOKEN}" \--data-urlencode "ci=${CI}" \--data-urlencode "birth_date=20000101" \--data-urlencode "auth_type=DREAMSECURITY_SMS"
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 회원번호(user_id) - CI(
ci) - 생년월일(
birth_date) - 인증기관 및 타입(
auth_type)
- 사용자 ID(
curl -v POST "http://kapi.kakao.com/v1/internal/user/register/auth_info" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id=123465" \-d "target_id_type=user_id" \--data-urlencode "ci=${CI}" \--data-urlencode "birth_date=20000101" \--data-urlencode "auth_type=DREAMSECURITY_SMS"
응답: 본인인증 정보 등록 완료
// HTTP/1.1 200 OK{"id": 1376016924429958784,"account_id": 2137160, // 카카오계정 ID 응답 권한 필요"registered": true}
응답: 실패, 기존 등록 값과 달라 등록할 수 없는 본인인증 정보
// HTTP/1.1 400 Bad Request{"msg": "failed to register auth info. different authentication information is stored.","code": -410}
| 메서드 | URL | 인증 방식 |
|---|---|---|
DELETE | 카카오http://kapi.kakao.com/v1/internal/user/deregister/auth_info공동체 https://kapi.kakao.com/v1/internal/user/deregister/auth_info | 액세스 토큰 서비스 앱 어드민 키 |
사용자 카카오계정에 등록한 서비스의 본인인증 정보를 삭제합니다. 서비스에서 수집한 본인인증 정보를 카카오에 저장한 경우, 서비스에서 해당 정보를 삭제할 때 카카오에도 삭제 요청을 해야 합니다. 이 API는 공동체 전용으로 카카오계정파트와 협의 후 권한을 받아야 사용할 수 있습니다.
헤더에 원하는 인증 방식별 정보를 담아 DELETE로 요청합니다. 요청 성공 시 HTTP 상태 코드 200을 반환하며 응답 바디는 없습니다.
참고: API 변경 사항
카카오계정에서 본인인증 정보 삭제는 2022년 3월 8일부터 새로운 버전으로 제공합니다. 신규 버전은 API의 용도를 보다 직관적으로 이해하고 사용할 수 있도록 변경되었습니다. 기존 버전인 /v1/internal/user/delete/auth_info의 정보는 링크에서 확인할 수 있습니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 | O |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_id | String | 사용자 ID | O |
| target_id_type | String | target_id 타입user_id: 회원번호account_id: 카카오계정 IDtalk_id: 카카오톡 회원번호 | O |
요청: 액세스 토큰 방식
- 파라미터: 없음
curl -v -X DELETE "http://kapi.kakao.com/v1/internal/user/deregister/auth_info" \-H "Authorization: Bearer ${ACCESS_TOKEN}"
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 회원번호(user_id)
- 사용자 ID(
curl -v -G -X DELETE "http://kapi.kakao.com/v1/internal/user/deregister/auth_info" \-H "Authorization: Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id=123456" \-d "target_id_type=user_id"
응답
HTTP/1.1 200 OK
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 카카오http://kapi.kakao.com/v1/internal/user/compare/auth_info공동체 https://kapi.kakao.com/v1/internal/user/compare/auth_info | 액세스 토큰 서비스 앱 어드민 키 |
서비스의 본인인증 정보가 카카오계정의 본인인증 정보와 일치하는지 비교합니다. 이 API는 공동체 전용으로 카카오계정파트와 협의 후 권한을 받아야 사용할 수 있습니다. 또한 이 API는 CI를 포함한 2차 본인인증 정보만 지원합니다.
헤더에 원하는 인증 방식별 정보를 담아 GET으로 요청합니다. 요청 시 CI(연계정보), 생년월일을 전달해야 합니다. 요청 성공 시 응답은 본인인증 정보 비교 결과(is_matched)를 반환합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: Bearer ${ACCESS_TOKEN}인증 방식, 액세스 토큰으로 인증 요청 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| ci | String | 서비스에서 자체 본인인증으로 획득한 사용자의 CI | O |
| birth_date | String | 사용자의 생년월일, YYYYMMDD 형식 | O |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}인증 방식, 서비스 앱 어드민 키로 인증 요청 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_id | String | 사용자 ID | O |
| target_id_type | String | target_id 타입user_id: 회원번호account_id: 카카오계정 IDtalk_id: 카카오톡 회원번호 | O |
| ci | String | 서비스에서 자체 본인인증으로 획득한 사용자의 CI | O |
| birth_date | String | 사용자의 생년월일, YYYYMMDD 형식 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Long | 회원번호 | O |
| account_id | Integer | 카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유 | X |
| is_matched | Boolean | 본인인증 정보 일치 여부
| O |
요청: 액세스 토큰 방식
- 파라미터: 없음
- CI(
ci) - 생년월일(
birth_date)
- CI(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/compare/auth_info" \-H "Authorization: Bearer ${ACCESS_TOKEN}" \--data-urlencode "ci=${CI}" \--data-urlencode "birth_date=20000101"
요청: 서비스 앱 어드민 키 방식
- 파라미터
- 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 회원번호(user_id) - CI(
ci) - 생년월일(
birth_date)
- 사용자 ID(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/compare/auth_info" \-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \-d "target_id=123465" \-d "target_id_type=user_id" \--data-urlencode "ci=${CI}" \--data-urlencode "birth_date=20000101"
응답: 본인인증 정보 일치
// HTTP/1.1 200 OK{"id": 1376016924429928784,"account_id": 2137160, // 카카오계정 ID 응답 권한 필요"is_matched": true}
응답: 본인인증 정보 불일치
// HTTP/1.1 200 OK{"id": 1376016924429928784,"account_id": 2137160, // 카카오계정 ID 응답 권한 필요"is_matched": false}