본문 바로가기메인 메뉴 바로가기사이드 메뉴 바로가기

kakao developers

관련사이트

사이드 메뉴

플랫폼 API

API 제공

전용 API

어드민 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)
회원번호idOOO
카카오계정 IDaccount_idOO
다음 회원 IDdaum_user_idOO
카카오톡 회원번호talk_user_idOO
고유 IDuuidO
프로필 정보(닉네임/프로필 사진)profileOO
연결 여부has_signed_upOO
연결 시각connected_atOO
싱크 연결 시각synched_atO
사용자 프로퍼티propertiesO
카카오계정(이메일)account_emailOO
유효 이메일 여부is_email_validOO
이메일 인증 여부is_email_verifiedOO
이름nameO
성별genderO
연령대age_rangeO
출생연도birtyearO
생일birthdayO
카카오계정(휴대전화번호)phone_numberO
카카오계정 가입일자account_creation_dateO
CI(연계정보)ciO
본인인증 받은 시각ci_authenticated_atO
본인확인정보(이름)legal_nameO
본인확인정보(생년월일)legal_birth_dateO
본인확인정보(성별)legal_genderO
본인확인정보(내외국인)is_koreanO
카카오톡 서비스 가입 여부is_kakaotalk_userOO
카카오계정 대표 정보display_idO
카카오계정 통합 여부unification_statusOO
그룹 사용자 토큰group_user_tokenOO
이름설명필수
AuthorizationAuthorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
이름타입설명필수
secure_resourceBoolean이미지 URL 값의 HTTPS 반환 여부 (기본값: false)X
property_keysString[]응답에 포함할 정보의 키, 미지정 시 모든 정보 포함
키와 값의 형식으로 구성
(예: ["id","properties.${CUSTOM_PROPERTY_KEY}",
"kakao_account.email"])
X
이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_idString사용자 정보를 가져올 사용자 IDO
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
  • uuid: 고유 ID
외부 API로 요청 시 user_id만 사용 가능
O
secure_resourceBoolean이미지 URL 값의 HTTPS 반환 여부 (기본값: false)X
property_keysString[]응답에 포함할 정보의 키, 미지정 시 모든 정보 포함
키와 값의 쌍으로 구성
(예: ["id","properties.${CUSTOM_PROPERTY_KEY}",
"kakao_account.email"])
X
  • 내부 API 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
Content-TypeContent-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_keyString사용자 정보를 가져올 서비스 앱의 키O(Optional)
target_app_idLong사용자 정보를 가져올 서비스 앱의 IDO(Optional)
target_access_tokenString사용자 정보를 가져올 사용자의 액세스 토큰 값O(Optional)
target_idString사용자 정보를 가져올 사용자 IDO(Optional)
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
  • uuid: 고유 ID
O(Optional)
secure_resourceBoolean이미지 URL 값의 HTTPS 반환 여부 (기본값: false)X
property_keysString[]응답에 포함할 정보의 키, 미지정 시 모든 정보 포함
키와 값의 쌍으로 구성
(예: ["id","properties.${CUSTOM_PROPERTY_KEY}",
"kakao_account.email"])
X
  • 요청 시 property_keys 파라미터로 조회할 정보를 지정한 경우, 응답은 해당 값만 제공
Permission
: 권한 필요, 사용자 정보 참고
Internal Only
: 내부 API 요청 시에만 제공
이름타입설명필수
idLong회원번호X
has_signed_upBoolean자동 연결 설정을 비활성화한 경우만 존재
수동 연결 호출의 완료 여부
연결 대기(Preregistered) 상태일 때는 false
연결(Registered) 상태일 때는 true
X
connected_atDatetime서비스에 연결 완료된 시각, UTC
(RFC3339 internet date/time 형식)
X
synched_atDatetime카카오싱크 간편가입으로 로그인한 시각, UTC
(RFC3339 internet date/time 형식)
X
group_user_token
Permission
String그룹 앱 설정 권한 필요
해당 앱이 그룹 앱에 속한 경우 그룹에서 맵핑(Mapping) 정보로 사용할 수 있는 값
그룹 정보가 변경되면 바뀔 수 있는 값이므로 사용자 ID로 사용하지 말 것
X
propertiesJSON사용자 프로퍼티(Property)
설정하기 > 사용자 프로퍼티 참고
X
kakao_accountKakaoAccount카카오계정 정보X
for_partner
Permission
ForPartner카카오 및 공동체 앱에만 제공하는 추가 정보X
Permission
: 권한 필요, 사용자 정보 참고
Internal Only
: 내부 API 요청 시에만 제공
has_${FIELD_NAME}: Deprecated, 각 사용자 정보 값 소유 여부(Boolean), 해당 사용자 정보의 제공 가능 여부를 확인하는 용도로 사용할 수 없음(참고: needs_agreement)
이름타입설명필수
profile_nickname_needs_agreementBoolean사용자 동의 시 닉네임 제공 가능

필요한 동의항목: 닉네임
X
profile_image_needs_agreementBoolean사용자 동의 시 프로필 사진 제공 가능

필요한 동의항목: 프로필 사진
X
profile_needs_agreementBoolean사용자 동의 시 프로필 정보(닉네임/프로필 사진) 제공 가능

필요한 동의항목: 프로필 정보(닉네임/프로필 사진)
X
profileProfile프로필 정보

필요한 동의항목: 닉네임, 프로필 사진, 프로필 정보(닉네임/프로필 사진)
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카카오계정 IDX
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
이름타입설명필수
nicknameString닉네임

필요한 동의항목: 닉네임 또는 프로필 정보(닉네임/프로필 사진)
X
thumbnail_image_urlString프로필 미리보기 이미지 URL, 110px * 110px 또는 100px * 100px

필요한 동의항목: 프로필 사진 또는 프로필 정보(닉네임/프로필 사진)
X
profile_image_urlString프로필 이미지 URL, 640px * 640px 또는 480px * 480px

필요한 동의항목: 프로필 사진 또는 프로필 정보(닉네임/프로필 사진)
X
is_default_imageBoolean프로필 이미지 URL이 기본 프로필 이미지 URL인지 여부
사용자가 등록한 프로필 이미지가 없을 경우, 기본 프로필 이미지 제공
  • true: 기본 프로필 이미지
  • false: 사용자가 등록한 프로필 이미지

필요한 동의항목: 프로필 사진 또는 프로필 정보(닉네임/프로필 사진)
X
is_default_nicknameBoolean닉네임이 기본 닉네임인지 여부
사용자가 등록한 닉네임이 운영정책에 부합하지 않는 경우, "닉네임을 등록해주세요"가 기본 닉네임으로 적용됨
  • true: 기본 닉네임
  • false: 사용자가 등록한 닉네임

필요한 동의항목: 프로필 정보(닉네임/프로필 사진) 또는 닉네임
X
Permission
: 권한 필요, 사용자 정보 참고
이름타입설명필수
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)
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)
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)
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)
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)
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"]'
  • 아래 예제는 참고를 위해 모든 항목을 포함하고 있으나, 실제 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
}
}
{
"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"
}
}
{
"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)가 응답에 포함됩니다.

이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_idsString[]조회할 사용자 ID 목록
최대 100명의 사용자 정보 요청 가능
property_keys로 사용자 정보를 지정해 요청하는 경우, 최대 20명의 사용자 정보 요청 가능
O
target_id_typeStringtarget_ids에 포함된 사용자 ID 타입, 아래 중 하나
  • user_id: 회원번호
  • uuid: 고유 ID
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
외부 API 요청 시, user_id 또는 uuid만 사용 가능
O
property_keysString[]응답에 포함할 사용자 프로퍼티의 키
사용자 정보앱 관리 페이지의 [카카오 로그인] > [고급] > [사용자 프로퍼티]에 지정된 키 사용 가능
미지정 시 기본 응답만 제공
X
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
  • 요청 대상 서비스 앱을 어떤 파라미터로 지정하는지에 따라 필수 파라미터 구성이 달라집니다.
    • 서비스 앱 키: target_app_key
    • 서비스 앱 ID: target_app_id
이름타입설명필수
target_app_keyString사용자 정보를 조회할 서비스 앱의 키O(Optional)
target_app_idString사용자 정보를 조회할 서비스 앱의 IDO(Optional)
target_idsString[]조회할 사용자 ID 목록
최대 100명의 사용자 정보 요청 가능
property_keys로 사용자 정보를 지정해 요청하는 경우, 최대 20명의 사용자 정보 요청 가능
O
target_id_typeStringtarget_ids에 포함된 사용자 ID 타입, 아래 중 하나
  • user_id: 회원번호
  • uuid: 고유 ID
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
외부 API 요청 시, user_id 또는 uuid만 사용 가능
O
property_keysString[]응답에 포함할 사용자 프로퍼티의 키
사용자 정보앱 관리 페이지의 [카카오 로그인] > [고급] > [사용자 프로퍼티]에 지정된 키 사용 가능
미지정 시 기본 응답만 제공
X
이름타입설명필수
elementsUserInfo[]사용자 정보 목록
여러 사용자 정보 조회 API의 기본 응답에서는 ID와 같은 일부 기본 정보만 포함
기본 응답 외 정보는 property_keys 파라미터로 지정해 응답에 포함하도록 요청 가능
요청 가능한 정보의 종류는 사용자 정보 참고
O
이름타입설명필수
idLong회원번호(user_id)O
synched_atDatetime카카오싱크 간편가입으로 로그인한 시각, UTC
(RFC3339 internet date/time format)
X
connected_atDatetime서비스에 연결 완료된 시각, UTC
(RFC3339 internet date/time format)
X
kakao_accountKakaoAccount카카오계정 정보X
propertiesJSON사용자 프로퍼티(key:value 형식)
property_keys 파라미터로 특정 사용자 프로퍼티만 요청한 경우, 해당 사용자 프로퍼티 값만 제공
X
  • 파라미터
    • 조회할 사용자 ID 목록(target_ids)
    • 사용자 ID 타입(target_id_type): 회원번호(user_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)
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
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는 샌드박스 페이즈에서만 샘플 앱으로 테스트 가능합니다.


샘플 앱 이외의 앱으로 테스트하려면 해당 앱에 필요한 권한을 받아야 합니다.

이름설명필수
AuthorizationAuthorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
이름타입설명필수
address_idLong배송지 정보가 많은 경우, 특정 배송지 정보만 얻고 싶을 때 배송지 ID 지정X
from_updated_atInteger배송지 정보를 여러 페이지에 나눠 조회 시, 조회 기준이 되는 배송지 수정 시각(updated_at)
유닉스 타임스탬프 형식의 시간 값(단위: 초)
(기본값: 0)
참고: 배송지 페이지네이션
X
page_sizeInteger배송지 정보를 여러 페이지에 나눠 조회 시, 한 페이지에 포함할 배송지 개수
(기본값: 10, 최소값: 2)
참고: 배송지 페이지네이션
X
  • 내부 API 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_idString배송지 정보를 가져올 사용자의 IDO
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
외부 API로 요청 시 user_id만 사용 가능
O
address_idLong배송지 정보가 많은 경우, 특정 배송지 정보만 얻고 싶을 때 배송지 ID 지정X
from_updated_atInteger배송지 정보를 여러 페이지에 나눠 조회 시, 조회 기준이 되는 배송지 수정 시각(updated_at)
유닉스 타임스탬프 형식의 시간 값(단위: 초)
(기본값: 0)
참고: 배송지 페이지네이션
X
page_sizeInteger배송지 정보를 여러 페이지에 나눠 조회 시, 한 페이지에 포함할 배송지 개수
(기본값: 10, 최소값: 2)
참고: 배송지 페이지네이션
X
  • 내부 API 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
Content-TypeContent-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_keyString배송지 정보를 가져올 앱의 키O(Optional)
target_app_idLong배송지 정보를 가져올 앱의 IDO(Optional)
target_access_tokenStringBearer 타입의 액세스 토큰 사용 시, 배송지 정보를 가져올 사용자의 액세스 토큰 값O(Optional)
target_idString배송지 정보를 가져올 사용자의 회원번호(user_id)O(Optional)
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
O(Optional)
address_idLong배송지 정보가 많은 경우, 특정 배송지 정보만 얻고 싶을 때 배송지 ID 지정X
from_updated_atInteger배송지 정보를 여러 페이지에 나눠 조회 시, 조회 기준이 되는 배송지 수정 시각(updated_at)
유닉스 타임스탬프 형식의 시간 값(단위: 초)
(기본값: 0)
참고: 배송지 페이지네이션
X
page_sizeInteger배송지 정보를 여러 페이지에 나눠 조회 시, 한 페이지에 포함할 배송지 개수
(기본값: 10, 최소값: 2)
참고: 배송지 페이지네이션
X
이름타입설명필수
user_idLong배송지 정보를 가져온 사용자 회원번호X
shipping_addresses_needs_agreementBoolean사용자 동의 시 배송지 정보 제공 가능X
shipping_addressesShippingAddress[]사용자의 배송지 정보 리스트
최신순 정렬
기본 배송지는 수정 시각과 관계 없이 첫 번째에 위치
X
has_shipping_addresses: Deprecated, 각 사용자 정보 값 소유 여부(Boolean), 해당 사용자 정보의 제공 가능 여부를 확인하는 용도로 사용할 수 없음(참고: needs_agreement)
이름타입설명필수
idLong배송지 IDO
nameString배송지명X
is_defaultBoolean기본 배송지 여부O
updated_atInteger배송지 수정 시각
유닉스 타임스탬프 형식의 시간 값(단위: 초)
X
typeString배송지 타입, 구주소(OLD, 지번 및 번지 주소) 또는 신주소(NEW, 도로명 주소)X
base_addressString우편번호 검색시 채워지는 기본 주소X
detail_addressString기본 주소에 추가하는 상세 주소X
receiver_nameString수령인 이름X
receiver_phone_number1String수령인 연락처X
receiver_phone_number2String수령인 추가 연락처X
zone_numberString신주소 우편번호, 신주소인 경우 반드시 존재X
zip_codeString구주소 우편번호
구주소는 우편번호를 소유하지 않는 경우가 있어, 구주소라도 해당 값이 없을 수 있음
X
  • 특정 배송지만 요청
  • 파라미터
    • 배송지 ID(address_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)
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"
}
]
}
{
"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_checktrue로 포함해야 하며, 별도 권한이 필요합니다.

요청 성공 시 응답은 result 파라미터로 지정한 ID 유형별 ID 값입니다. 각 ID 값은 제공 조건을 만족해야만 응답에 포함됩니다.

이름설명필수
AuthorizationAuthorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
이름타입설명필수
resultsString조회할 ID 종류, 아래 중 하나 이상의 값 사용 가능, 여러 개 사용 시 쉼표(,)로 구분
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
  • uuid: 고유 ID
(예: account_id,talk_id)
O
skip_account_check
Permission
Boolean조회 대상 카카오계정의 제재 또는 휴면 상태 무시 여부
  • true: 제재 또는 휴면 상태와 상관없이 조회 결과 응답
  • false: 제재 또는 휴면 상태인 경우 에러 응답(기본값)
X
  • 내부 API 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_idString사용자 IDO
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
  • uuid: 고유 ID

참고: ID 종류
O
resultsString조회할 ID 종류, 아래 중 하나 이상의 값 사용 가능, 여러 개 사용 시 쉼표(,)로 구분
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
  • uuid: 고유 ID
(예: account_id,talk_id)
O
skip_account_checkBoolean조회 대상 카카오계정의 제재 또는 휴면 상태 무시 여부
  • true: 제재 또는 휴면 상태와 상관없이 조회 결과 응답
  • false: 제재 또는 휴면 상태인 경우 에러 응답
X
  • 내부 API 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
Content-TypeContent-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_keyString앱 키O(Optional)
target_app_idLong앱 IDO(Optional)
target_access_tokenString사용자의 액세스 토큰 값O(Optional)
target_idString사용자 IDO(Optional)
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
  • uuid: 고유 ID

참고: ID 종류
O(Optional)
resultsString조회할 ID 종류, 아래 중 하나 이상의 값 사용 가능, 여러 개 사용 시 쉼표(,)로 구분
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
  • uuid: 고유 ID
(예: account_id,talk_id)
O
skip_account_checkBoolean조회 대상 카카오계정의 제재 또는 휴면 상태 무시 여부
  • true: 제재 또는 휴면 상태와 상관없이 조회 결과 응답
  • false: 제재 또는 휴면 상태인 경우 에러 응답
X
  • 요청 시 results 파라미터로 지정한 ID 유형 중 제공 가능한 항목만 응답에 포함
이름타입설명필수
user_idLong회원번호

제공 조건: 해당 사용자의 회원번호가 존재하는 경우
X
account_idInteger카카오계정 ID

제공 조건: 카카오계정 ID 응답 권한이 있는 경우
X
talk_idLong카카오톡 회원번호

제공 조건: 해당 사용자가 카카오톡 사용자이고 카카오톡 회원번호 응답 권한이 있는 경우
X
uuidString사용자 고유 IDX
  • 파라미터
    • 조회할 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)
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를 호출하려면 각 앱에서 사용자가 로그인 및 수동 연결을 해야 합니다. 그룹에 속해 있는 앱이라도 사용자가 연결되어 있지 않은 경우에는 앱 기본 정보와 사용자 회원번호를 제공하지 않습니다.
  • 카카오싱크 간편가입 사용 시, 각 앱의 서비스 약관을 별도로 등록해야 합니다.
이름설명필수
AuthorizationAuthorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
  • 내부 API 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_idString그룹 내 사용자 정보를 가져올 사용자 IDO
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
O
이름타입설명필수
group_user_tokenString해당 앱이 그룹에 속해 있을 때만 존재
그룹에서 맵핑 정보로 사용할 수 있는 값
그룹 정보가 변경되면 바뀔 수 있는 값이니 id로 사용할 수 없음
X
group_infoUserGroupInfoResult[]그룹에 속한 앱 중 사용자가 가입한 앱의 정보와 해당 앱에서의 회원번호(user_id)X
이름타입설명
user_idLong회원번호, 이 앱에서의 사용자 식별자
appAppDefaultInfo앱 정보
이름타입설명
idInteger앱 ID
nameString앱 이름
companyString앱 회사명
  • 파라미터: 없음
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)
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 객체를 받습니다.

이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
이름타입설명필수
account_idsInteger[]카카오계정 ID 목록
최대 200개의 카카오계정 ID 전달 가능
O
registered_user_onlyBoolean그룹 사용자 토큰을 생성할 사용자 범위 (기본값: true)
  • true: 호출한 앱과 연결된 사용자(휴면 및 제재 계정 포함)의 카카오계정 ID만 그룹 토큰 생성
  • false: 앱과 연결되지 않은 모든 사용자의 카카오계정 ID도 그룹 토큰 생성

중요: 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
}
// 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: 추가 정보 표를 참고합니다.

이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
Content-TypeContent-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_keyString연결 정보를 확인할 서비스 앱의 키O(Optional)
target_app_idInteger앱 연결 정보를 가져올 서비스 앱의 IDO(Optional)
target_access_tokenString앱 연결 정보를 가져올 사용자의 액세스 토큰 값O(Optional)
target_idString연결된 앱 정보를 확인할 사용자 IDO(Optional)
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
O(Optional)
resultsString앱과 사용자의 기본정보 외에 가져오고 싶은 추가 정보를 지정하는 파라미터
전달한 키 값에 따라 응답 구성 다름
(예: "results=app_key,app_scopes")
(기본값: null)

아래 중 원하는 정보의 키를 하나의 문자열에 쉼표(,)로 구분해 전달:
  • owner_developer: 앱의 소유자(OWNER)인 개발자 정보
  • app_business_info: 앱의 비즈니스 정보(구성: 비즈 앱 여부, 비즈채널 앱 여부, 앱에 등록된 사업자번호)
  • app_detail: 앱 상세 정보(구성: 앱 ID, 회사명, 앱 이름, 앱 타입, 앱 상태, 앱 카테고리, 앱 아이콘, 카카오 로그인 사용 여부)
  • app_key: 앱 키 정보(구성: 앱 키 타입, 앱 키)
  • app_key_detail: 앱 키 정보, OS별 앱 실행 커스텀 URL, Android/iOS 마켓 URL
  • kakao_sync: 카카오싱크 이용 정보(구성: 카카오 로그인 활성화 여부, 카카오싱크 간편가입 활성화 여부, 앱의 서비스 약관 정보, 회원가입 플러그인 URL)
  • ecp: ECP 앱 여부(구성: ECP 타입(회사명))
  • kakao_biz_service: 비즈니스 성격(B2B)의 서비스인지 여부(구성: 비즈니스 성격(B2B)의 서비스인지 여부)
  • not_allowed_under14: 14세 미만 사용자 제한 여부(구성: 14세 미만 사용자 앱 제한 여부)
  • app_scopes: 앱에 설정된 동의항목 목록(구성: 카카오 로그인 활성화 여부, 앱에 설정된 동의항목 목록)
  • app_channel_scopes: 앱에 설정된 채널별 동의항목 목록(구성: 카카오 로그인 활성화 여부, 앱에 설정된 채널별 동의항목 목록)
X
이름타입설명필수
user_idLong회원번호O
user_statusString사용자 상태, 아래 중 하나
  • REGISTERED: 연결
  • PREREGISTERED: 연결 대기
  • NONE: 앱과 연결되지 않았으나 회원번호 사전 발급으로 회원번호를 발급받은 사용자
O
account_idInteger사용자의 카카오계정 ID

제공 조건: 카카오계정 ID 응답 권한 보유
X
talk_user_idLong사용자의 카카오톡 회원번호

제공 조건: 카카오톡 회원번호(talk_id) 응답 권한 보유
X
auth_levelString앱의 연령인증 레벨, 아래 중 하나
  • AUTH_LEVEL1: 연령인증
  • AUTH_LEVEL2: 본인인증

제공 조건: 조회 대상 앱이 카카오게임 중 2차 연령인증이 설정된 리치보드게임인 경우
X
age_limitInteger앱에 설정된 제한 연령

제공 조건: 조회 대상 앱이 카카오게임 중 2차 연령인증이 설정된 리치보드게임인 경우
X
idInteger앱 IDO
nameString앱 이름O
companyString회사명X
typeString앱 타입, 아래 중 하나
  • DEFAULT: 일반 앱
  • SAMPLE: 샘플 앱
  • KAKAO: 인하우스 앱
  • PARTNER: 공동체 앱
  • DAUM: 다음 앱
  • GAME: 게임 앱
참고: 카카오디벨로퍼스 앱 타입
O
statusString앱 상태, 아래 중 하나
  • ACTIVE: 활성
  • BLOCKED: 차단
O
categoryString앱 카테고리O
phaseString테스트 앱 여부, 아래 중 하나
  • NORMAL: 일반 앱
  • TEST: 테스트 앱
O
owner_developerDeveloperInfo앱의 소유자(OWNER)인 개발자 정보

제공 조건: 요청 시 results 파라미터에 owner_developer를 포함한 경우
X
app_business_infoAppBusinessInfo앱의 비즈니스 정보

제공 조건: 요청 시 results 파라미터에 app_business_info를 포함한 경우
X
icon_image_urlString앱 아이콘 이미지 URL(http 형식)

제공 조건: 요청 시 results 파라미터에 app_detail를 포함한 경우
X
secure_icon_image_urlString앱 아이콘 이미지 URL(https 형식)

제공 조건: 요청 시 results 파라미터에 app_detail를 포함한 경우
X
user_managementString카카오 로그인 활성화 여부, 아래 중 하나
  • ON:활성화
  • OFF: 비활성화

제공 조건: 요청 시 results 파라미터에 아래 키 중 하나라도 포함한 경우
  • app_detail
  • app_scopes
  • app_channel_scopes
  • kakao_sync
O
app_keysAppKey[]조회 대상인 앱의 앱 키 목록
target_app_key로 요청한 경우, 요청한 키가 REST API 키가 아니라면 응답에 REST API 키 포함, 위 제공 조건에 만족할 경우 해당 앱 키와 REST API 키를 포함하고 권한이 없는 경우 해당 앱 키만 응답

제공 조건: 요청 시 results 파라미터에 app_key_detail 또는 app_key를 포함하고 target_app_key로 요청 시 포함한 경우
API 응답 권한 보유 시에만 포함
X
execution_urlExecutionUrl[]OS별 앱 실행 커스텀 URL

제공 조건: 요청 시 results 파라미터에 app_key_detail를 포함한 경우
X
market_urlMarketUrl[]OS별 앱 설치 커스텀 URL

제공 조건: 요청 시 results 파라미터에 app_key_detail를 포함한 경우
X
app_key_typeString앱 키 타입으로 아래 중 하나
  • NATIVE_APP_KEY
  • REST_API_KEY
  • JAVASCRIPT_KEY
  • ADMIN_KEY

중요:
target_app_key로 요청한 경우, 해당 앱 키의 타입
target_app_id로 요청 시, 권한에 따라 해당 앱의 앱 키 제공(현재 REST_API_KEY만 지원)
제공 조건: 요청 시 results 파라미터에 app_key를 포함한 경우
X
app_keyStringapp_key_type에 해당하는 앱 키 값

제공 조건: 요청 시 results 파라미터에 app_key를 포함한 경우
X
kakao_syncString카카오싱크 간편가입 활성화 여부, 아래 중 하나
  • ON: 활성화
  • OFF: 비활성화

중요: 카카오 로그인이 비활성화되어 있어 응답의 user_management 값이 OFF인 경우 제공하지 않음
카카오싱크 검수를 통과하지 않아 간편가입 기능의 사용 권한이 없는 경우의 값은 OFF
제공 조건: 요청 시 results 파라미터에 kakao_sync를 포함한 경우
X
service_termsServiceTerm[]카카오싱크 간편가입을 사용하는 앱의 서비스 약관 정보
카카오싱크 검수를 통과해 약관이 등록된 경우 서비스 약관 정보 제공
카카오 로그인이 비활성화되어 있어 응답의 user_management 값이 OFF인 경우 제공하지 않음

제공 조건: 요청 시 results 파라미터에 kakao_sync를 포함한 경우
X
biz_pluginBizPlugin회원가입 플러그인을 사용하는 경우 포함, t1, t2 URL

제공 조건: 회원가입 플러그인 권한 보유한 경우, 요청 시 results 파라미터에 kakao_sync를 포함한 경우
X
ecp_typeStringECP 타입(회사명)
ECP앱이 아닌 경우 미제공, 아래 중 하나
  • ECP_SIXSHOP: 식스샵
  • ECP_MAKESHOP: 메이크샵
  • ECP_NHN_COMMERCE: NHN 커머스
  • ECP_CAFE24: 카페24
  • ECP_IMWEB: 아임웹
  • ECP_FIRSTMALL: 퍼스트몰
  • ECP_WISA: 위사

제공 조건: 요청 시 results 파라미터에 ecp를 포함한 경우
X
kakao_biz_serviceBoolean비즈니스 성격(B2B)의 서비스인지 여부

제공 조건: 요청 시 results 파라미터에 kakao_biz_service를 포함한 경우
O
not_allowed_under14Boolean14세 미만 사용자 앱 제한 여부
  • true: 14세 미만 사용자를 허용하지 않는 앱일 경우
  • false: 나이 제한이 없는 경우

제공 조건: 요청 시 results 파라미터에 not_allowed_under14를 포함한 경우
O
user_managementString카카오 로그인 활성화 여부, 아래 중 하나
  • on: 활성화
  • off: 비활성화

제공 조건: 요청 시 results 파라미터에 아래 키 중 하나라도 포함한 경우
  • app_detail
  • app_scopes
  • app_channel_scopes
  • kakao_sync
O
app_scopesAppScope[]앱에 설정된 동의항목 목록

제공 조건: 카카오 로그인이 활성화되어 있어 응답의 user_management 값이 ON인 경우, 요청 시 results 파라미터에 app_scopes를 포함한 경우
X
app_channel_scopesAppScope[]앱에 설정된 채널별 동의항목 목록

제공 조건: 카카오 로그인이 활성화되어 있어 응답의 user_management 값이 ON인 경우, 요청 시 results 파라미터에 app_channel_scopes를 포함한 경우
X
이름타입설명필수
idInteger개발자 IDO
account_idInteger개발자의 카카오계정 ID

제공 조건: 카카오계정 ID 응답 권한 보유
X
registered_atString개발자 가입 시각(RFC3339 internet date/time 형식)O
deactivatedBoolean개발자 계정이 휴면 계정 탈퇴 처리로 탈퇴된 경우, 서비스에 영향을 주기 않기 위해 탈퇴된 상태로 소유자(OWNER) 정보가 남으며, 이 경우에만 true 값으로 제공O
이름타입설명필수
app_key_typeString앱 키 타입으로 아래 중 하나
  • NATIVE_APP_KEY
  • REST_API_KEY
  • JAVASCRIPT_KEY
  • ADMIN_KEY

중요:
target_app_key로 요청한 경우, 해당 앱 키의 타입
target_app_id로 요청 시, 권한에 따라 해당 앱의 앱 키 제공(현재 REST_API_KEY만 지원)
제공 조건: 요청 시 results 파라미터에 app_key_detail를 포함한 경우
X
app_keyStringapp_key_type에 해당하는 앱 키 값

제공 조건: 요청 시 results 파라미터에 app_key_detail를 포함한 경우
X
이름타입설명필수
biz_appBoolean비즈 앱 여부, 앱의 사업자번호 등록 여부O
biz_plus_friends_appBoolean비즈채널 앱 여부, 앱과 연결된 비즈니스 채널 존재 여부O
business_numberString앱에 등록된 사업자번호X
이름타입설명필수
platformString플랫폼 정보, 아래 중 하나
  • android
  • iOS
  • iPad
  • web
O
pkgnamesString[]platformandroid인 경우, 앱에 설정된 안드로이드 패키지 이름(Package name) 목록X
urlsString[]platformiOSiPad인 경우, 앱에 설정된 커스텀 URL 스킴
platformweb인 경우, 앱에 설정된 웹 도메인 목록
X
이름타입설명필수
platformString플랫폼 정보, 아래 중 하나
  • android
  • iOS
  • iPad
  • web
O
urlsString[]앱 설치 URL 목록X
이름타입설명필수
tagString약관 태그(tag)
서비스 약관 선택해 동의 요청에 사용
O
title_koString한글 제목O
title_enString영문 제목O
title_jaString일본어 제목X
title_zhString중국어(간체) 제목X
title_zhtwString중국어(번체) 제목X
urlString상세 URLX
requiredBoolean해당 약관이 필수 동의해야 하는 항목인지 여부, 아래 중 하나
  • true: 필수 동의항목
  • false: 선택 동의항목
O
orderInteger약관이 보여지는 순서O
created_atDatetime약관 생성 시각(RFC3339 internet date/time 형식)O
updated_atDatetime약관 수정 시각(RFC3339 internet date/time 형식)O
이름타입설명필수
third_terms_info_uriStringt1, 공통플러그인용, 서비스 제공자(Third party)의 약관을 가져오는 URL

제공 조건: 공통플러그인 권한 보유
X
third_terms_agreement_uriStringt2, 공통플러그인용, 서비스 제공자(Third party)의 약관에 동의하는 URL

제공 조건: 공통플러그인 권한 보유
X
이름타입설명필수
idString동의항목 IDO
displayString동의항목 이름, KA 헤더의 언어(language)에 따라 한글 또는 영어로 제공O
scope_typeString동의항목 타입, 아래 중 하나
  • privacy: 개인정보 동의항목
  • service: 접근권한 동의항목
O
requiredBoolean필수 동의항목으로 설정되었는지 여부
해당 동의항목을 사용하도록 설정하지 않은 경우 false
O
collectingBoolean수집 후 제공 설정 여부
해당 동의항목을 사용하도록 설정하지 않았고, 수집 후 제공을 설정하지 않았다면 false
O
usingBoolean사용 중인 동의항목인지 여부
해당 동의항목을 필수 동의 또는 선택 동의로 설정한 경우 true, 사용안함으로 설정한 경우 false
O
has_permissionBoolean동의항목을 설정할 수 있는 권한 소유 여부
해당 동의항목을 설정할 수 있는 권한이 있는 경우 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)
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 //권한 필요
}
  • 요청 시 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 //권한 필요
}
  • 요청 시 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의 경우, 연결 없음(NONE) 상태와 함께 연결 끊음(DEREGISTERED) 상태를 포함함, 연결 상태 참고

사용자의 앱 연결 이력을 조회합니다. 이 API는 아래와 같은 용도로 사용할 수 있습니다.

  • 사용자와 앱의 연결 상태 확인
  • 사용자의 앱 최초 연결(서비스 첫 가입) 여부 확인 (latest_deregistered_info 필드 존재 여부로 판단 가능)
  • 서비스의 재가입 유예 정책 적용을 위한 사용자 연결 및 연결 해제 이력 확인
  • 사용자와 연결 이력이 있는 앱의 기본 정보 조회

헤더에 원하는 인증 정보를 담아 GET으로 요청하고, 성공 시 앱 기본 정보와 사용자의 앱 연결 이력을 받습니다. 응답 중 카카오계정 ID(account_id)는 권한이 있는 앱에서 요청한 경우에만 응답에 포함됩니다.

2021년 12월 28일부터 연결된 앱 연결 이력 조회 API가 새로운 버전으로 제공됩니다.

이 API는 샌드박스 페이즈에서만 샘플 앱으로 테스트 가능합니다.


샘플 앱 이외의 앱으로 테스트하려면 해당 앱에 필요한 권한을 받아야 합니다.

이름설명필수
AuthorizationAuthorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_idString앱 연결 이력을 조회할 사용자 IDO
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
O
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
Content-TypeContent-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_keyString사용자의 앱 연결 이력을 조회할 서비스 앱의 키O(Optional)
target_app_idLong사용자의 앱 연결 이력을 조회할 서비스 앱의 IDO(Optional)
target_access_tokenString앱 연결 이력을 조회할 사용자의 액세스 토큰O(Optional)
target_idString앱 연결 이력을 조회할 사용자 IDO
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
여러 사용자를 대상으로 요청하는 target_app_ids 파라미터 사용 시에는 account_id만 사용 가능
O
이름타입설명필수
user_idLong회원번호
연결 끊음(DEREGISTERED) 상태인 사용자인 경우 응답에 포함되지 않음

참고: 사용자 ID 고정 시, 연결 해제 전후의 회원번호 동일
X
account_idInteger사용자의 카카오계정 ID

제공 조건: 카카오계정 ID 응답 권한 보유
X
user_statusString사용자와 앱의 연결 상태, 아래 중 하나
  • REGISTERED: 연결
  • PREREGISTERED: 연결 대기
  • NONE: 앱과 연결되지 않았으나 회원번호 사전 발급으로 회원번호를 발급받은 사용자
  • DEREGISTERED: 연결 끊음
O
registered_atDatetime사용자의 앱 연결 시각, UTC
현재 앱에 연결 상태일 때만 존재
(RFC3339 internet date/time 형식)
X
latest_deregistered_infoLatestDeregisteredInfo마지막 연결 해제 이력
앱과 최초 연결 또는 연결 대기 상태가 되어 연결 해제 이력이 없는 사용자의 경우 미존재
X
appApp앱 정보O
이름타입설명필수
user_idLong연결 해제 이전의 회원번호

참고: 사용자 ID 고정 시, 연결 해제 전후의 회원번호 동일
O
deregistered_atDatetime마지막 연결 해제 시각, UTC
(RFC3339 internet date/time 형식)
O
이름타입설명필수
idInteger앱 IDO
nameString앱 이름O
companyString회사명(상호, 법인 또는 단체명)O
typeString앱 타입, 아래 중 하나
  • DEFAULT: 일반 앱
  • SAMPLE: 샘플 앱
  • KAKAO: 인하우스 앱
  • PARTNER: 공동체 앱
  • DAUM: 다음 앱
  • GAME: 게임 앱

참고: 카카오디벨로퍼스 앱 타입
O
statusString앱 상태, 아래 중 하나
  • ACTIVE: 활성
  • BLOCKED: 차단
O
categoryString앱 카테고리O
app_keyString앱 키
앱 키로 요청 시, 해당 앱 키
앱 ID로 요청 시, 권한에 따라 대상 앱의 앱 키 제공(현재 REST API 키만 지원)
액세스 토큰으로 요청 시, 토큰 발급에 사용된 앱 키
X
app_key_typeStringapp_key의 타입, 아래 중 하나
  • NATIVE_APP_KEY
  • REST_API_KEY
  • JAVASCRIPT_KEY
  • ADMIN_KEY
X
phaseString테스트 앱 여부, 아래 중 하나
  • NORMAL: 일반 앱
  • TEST: 테스트 앱
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)
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)
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}"
}
}
// 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}"
}
}
// 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인 카카오계정은 카카오 로그인으로 토큰을 발급받을 수 없고, 기존 액세스 토큰의 갱신도 불가능합니다.

이름설명필수
AuthorizationAuthorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_idStringtarget_id_type에 해당하는 사용자 IDO
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
O
  • 내부 API 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
Content-TypeContent-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_keyString카카오계정 상태를 확인할 서비스 앱의 키O(Optional)
target_app_idLong카카오계정 상태를 확인할 서비스 앱의 IDO(Optional)
target_access_tokenString카카오계정 상태를 확인할 사용자의 액세스 토큰 값O(Optional)
target_idString카카오계정 상태를 확인할 사용자 IDO(Optional)
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
O(Optional)
이름타입설명필수
idLong회원번호O
account_id
Permission
Long카카오계정 ID

제공 조건: 카카오계정 ID 응답 권한 보유
X
user_statusString사용자의 앱 연결 상태, 아래 중 하나
  • REGISTERED: 연결
  • PREREGISTERED: 연결 대기
O
login_availableBoolean카카오계정 로그인 가능 여부

필요한 동의항목: 카카오계정(전화번호) 또는 카카오계정(이메일)
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)
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)
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 응답 권한이 없어 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 또는 회원번호로 사용자 정보 조회를 요청해 제공 받을 수 있습니다.

이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_idString카카오계정 ID를 조회할 사용자의 카카오계정 이메일 또는 전화번호
한국 번호인 경우 821012345678+82 10-1234-5678로 요청
(참고: libphonenumber)
O
target_id_typeStringtarget_id의 타입, EMAIL(이메일) 또는 PHONE_NUMBER(전화번호)O
이름타입설명필수
idLong회원번호O
account_idInteger카카오계정 ID

제공 조건: 카카오계정 ID 응답 권한 보유
X
user_statusString사용자의 앱 연결 상태, 아래 중 하나
  • REGISTERED: 연결
  • PREREGISTERED: 연결 대기
O
  • 파라미터
    • 사용자 ID(target_id)
    • 사용자 ID 타입(target_id_type): 이메일(EMAIL)
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)
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)
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
}
// 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를 함께 제공합니다.

이름설명필수
AuthorizationAuthorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_idStringtarget_id_type에 해당하는 사용자 IDO
target_id_typeString아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호(기본값: account_id)
X
이름타입설명필수
idLong회원번호O
account_idInteger카카오계정 ID

제공 조건: 카카오계정 ID 응답 권한 보유
X
user_statusString앱과 사용자의 연결 상태, 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):
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_agentKA 헤더 인증을 위한 서비스의 요청 환경 정보를 전달해야 하며, 전달된 값을 서비스 앱 정보와 비교해 올바른 요청인지 인증합니다. 이 API는 기본적으로 연결 상태인 사용자 대상으로만 호출 가능하지만, 비로그인 서비스의 경우 account_id를 사용해 연결 상태와 관계 없이 호출할 수 있습니다.

요청 성공 시 응답은 사용자 액세스 토큰과 앱 키에 해당하는 앱의 정보를 포함합니다. 인증 실패 시 에러로 응답하며 결과를 extras.detail_cause에 안내합니다.

  • 내부 API 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
Content-TypeContent-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_keyString서비스 앱의 키
JavaScript 키 또는 네이티브 앱 키만 사용 가능
O(Optional)
target_idString사용자 IDO(Optional)
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
O(Optional)
target_access_tokenString서비스 앱의 사용자 액세스 토큰O(Optional)
account_idInteger카카오계정 IDO(Optional)
target_kakao_agentString서비스로부터 전달받은 KA 헤더
액세스 토큰 발급 시 사용된 앱 키 타입에 따라 아래 정보를 반드시 포함해야 함
네이티브 앱 키: os, origin
REST API 키: ip
JavaScript 키: os, origin
O
resultsString앱의 추가 정보 요청, 아래 값 사용
app_platform: 플랫폼 정보
X
이름타입설명필수
app_infoAppInfo앱 정보O
user_idLong사용자의 회원번호

제공 조건: 사용자가 앱에 연결 또는 연결 대기 상태인 경우
중요: target_id, target_id_type을 사용해 account_id로 요청한 경우 제공하지 않음
X
account_idInteger사용자의 카카오계정 ID

제공 조건: 카카오계정 ID 응답 권한 보유
X
talk_user_idLong사용자의 카카오톡 회원번호

제공 조건: 카카오톡 회원번호(talk_id) 응답 권한 보유
X
이름타입설명필수
idInteger앱 IDO
nameString앱 이름O
companyString회사명O
typeString앱 타입O
categoryString앱 카테고리O
secure_icon_image_urlString앱 아이콘 이미지 URLO
app_keyString요청 시 사용한 앱 키O
app_key_typeString요청 시 사용한 앱 키 타입O
execution_urlExecutionUrl[]OS별 앱 실행 커스텀 URL

제공 조건: 요청 시 results 파라미터에 app_platform을 포함한 경우
X
market_urlMarketUrl[]OS별 앱 설치 커스텀 URL

제공 조건: 요청 시 results 파라미터에 app_platform을 포함한 경우
X
이름타입설명필수
platformString플랫폼 정보, 아래 중 하나
  • android
  • iOS
  • iPad
  • web
O
pkgnamesString[]platformandroid인 경우, 앱에 설정된 안드로이드 패키지 이름(Package name) 목록X
urlsString[]platformiOSiPad인 경우, 앱에 설정된 커스텀 URL 스킴
platformweb인 경우, 앱에 설정된 도메인 웹 목록
X
이름타입설명필수
platformString플랫폼 정보, 아래 중 하나
  • android
  • iOS
  • iPad
  • web
O
urlsString[]앱 설치 URL 목록X
  • 인증 실패 시 에러 응답extras 및 하위 필드에 결과 안내
이름타입설명필수
detail_causeString인증 실패 원인, 아래 중 하나
  • INVALID_TOKEN: 액세스 토큰이 만료되었거나, 액세스 토큰과 앱 키에 해당하는 앱이 일치하지 않음
  • INVALID_APP_KEY: 앱 키가 올바르지 않음
  • DEACTIVATED_APP_KEY: 비활성화된 앱 키 사용
  • INVALID_PLATFORM: KA 헤더 값이 올바르지 않음
  • INVALID_APP_KEY_TYPE: 허용되지 않은 플랫폼 키 사용
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"
}
}
// 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으로 요청하고, 성공 시 사용자의 회원번호를 받습니다.

이름형식설명
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
서비스 구분을 위해 서비스 앱의 앱 ID, 앱 키, 토큰 중 하나 파라미터로 전달 필요
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_app_idLong서비스 앱 IDO
target_idStringtarget_id_type에 해당하는 사용자 IDO
target_id_typeString아래 중 하나
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호(기본값: account_id)
X
이름타입설명필수
idString서비스의 회원번호(app_user_id)O
statusString사용자 상태, 아래 중 하나
  • NONE: 미연결
  • REGISTERED: 연결
  • PREREGISTERED: 연결 대기
  • CHECK_AGE_AUTH: 연령인증 정보가 초기화되어 다시 연령인증이 필요한 사용자

참고: PREREGISTERED, CHECK_AGE_AUTH 상태는 회원번호를 사용하는 앱에만 존재
O
  • 파라미터
    • 서비스 앱 ID(target_app_id)
    • 사용자 ID(target_id)
    • 사용자 ID 타입(target_id_type): 카카오계정 ID(account_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 사용 권한 신청
  • 데이터 사용 목적에 따라 [서비스 이용내역으로 추정한 정보] 동의항목의 설정 권한 부여
분석 데이터동의항목
추정 연령대
추정 성별
서비스 이용내역으로 추정한 정보(연령대,성별)¹⁾
추정 관심사서비스 이용내역으로 추정한 정보(관심사)¹⁾²⁾
1) 이용자의 서비스 이용내역에 대한 인구통계학적 특성과 이용자의 관심, 기호, 성향의 추정을 의미함 2) 카카오페이의 경우, 별도 동의항목 사용(금융데이터 분석 및 활용을 위한 데이터 제공)

사용자의 카카오 플랫폼 내 서비스 이용내역을 분석해 추정한 성별, 연령대, 관심사 정보를 받습니다. 이 API는 공동체 전용으로 필요한 동의항목을 참고해 권한을 받아야 사용할 수 있습니다. 카카오 서비스의 경우, Data Universe에서 필요한 데이터를 제공받을 수 있습니다. (참고: 카카오크루: 데이터 신청/제공, 카카오공동체크루: 데이터 신청/제공)

이 API는 연결 완료(REGISTERED)된 사용자를 대상으로만 호출할 수 있습니다. 각 분석 데이터의 필요한 동의항목을 설정하고, 사용자가 각 항목에 동의한 경우에 한해 응답에 정보가 포함됩니다.

원하는 인증 정보를 헤더에 담아 GET으로 요청하고, 성공 시 사용자의 분석 데이터를 받습니다. 관심사는 카테고리 형태로 제공하며, 자세한 카테고리 정보는 User Finding Operation을 참고합니다.

알파(Alpha)와 샌드박스(Sandbox) 페이즈(Phase)에서는 실제 데이터가 없어 모의 데이터(Mock data) 응답을 제공하고, 베타(Beta)와 프로덕션(Production) 페이즈에서만 실제 사용 가능한 데이터로 응답을 제공하는 점에 유의합니다.

응답 중 카카오계정 ID(account_id)는 권한이 있는 앱에서 내부 API로 요청한 경우에만 응답에 포함됩니다.

이름설명필수
AuthorizationAuthorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_idString분석 데이터를 가져올 사용자 IDO
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
O
이름타입설명필수
idLong사용자 회원번호(user_id)O
account_idInteger사용자의 카카오계정 ID

제공 조건: 카카오계정 ID 응답 권한 보유
X
age_groupAgeGroupInfo추정 연령대

필요한 동의항목: 서비스 이용내역으로 추정한 정보(연령대,성별)
X
genderString추정 성별
female: 여성
male: 남성

필요한 동의항목: 서비스 이용내역으로 추정한 정보(연령대,성별)
X
interestsInterestInfo[]추정 관심사

필요한 동의항목: 서비스 이용내역으로 추정한 정보(관심사)
X
이름타입설명
10_year_age_bandInteger10세 단위 연령대

  • 0: 추정 불가
  • 10: 0세~19세
  • 20: 20세~29세
  • 30: 30세~39세
  • 40: 40세~49세
  • 50: 50세~59세
  • 60: 60세~69세
  • 70: 70세~89세
5_year_age_bandInteger5세 단위 연령대

  • 0: 추정 불가
  • 10: 0세~14세
  • 15: 15세~19세
  • 20: 20세~24세
  • 25: 25세~29세
  • 30: 30세~34세
  • 35: 35세~39세
  • 40: 40세~44세
  • 45: 45세~49세
  • 50: 50세~54세
  • 55: 55세~59세
  • 60: 60세~64세
  • 65: 65세~69세
  • 70: 70세~89세
이름타입설명
full_category_idString관심사 카테고리 ID
full_category_nameStringfull_category_id와 하위 단계 카테고리 이름으로 구성된 관심사 카테고리 정보
simple_category_idStringfull_category_id의 가장 상위 단계인 depth1의 카테고리 ID
simple_category_nameStringsimple_category_id와 해당 카테고리 이름으로 구성된 가장 상위 관심사 카테고리 정보
scoreDouble관심도 수치(최소: 0, 최대: 1)
extra_scoresMap<String, Double>관심사를 다각도로 분석해볼 수 있도록 기본 관심도 수치(score) 외에 제공하는 추가 관심도 수치
depthDepthInfo관심사 카테고리의 단계 구분(depth) 상세 정보
이름타입설명
countInteger관심사 카테고리의 총 단계 구분(depth) 수
depth1_category_nameStringdepth1의 카테고리명
  • 파라미터: 없음
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)
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인 경우에만 공동체 앱: 카카오계정에 본인인증 정보 등록로 카카오계정에 서비스의 본인인증 정보를 등록할 수 있습니다.

본인인증 정보 등록 가능 여부 조회는 2022년 3월 8일부터 새로운 버전으로 제공합니다. 신규 버전은 API의 용도를 보다 직관적으로 이해하고 사용할 수 있도록 변경되었습니다. 기존 버전인 /v1/internal/user/verify/auth_info의 정보는 링크에서 확인할 수 있습니다.

이름설명필수
AuthorizationAuthorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
이름타입설명필수
ciString서비스에서 자체 본인인증으로 획득한 사용자의 CIO
birth_dateString사용자의 생년월일, YYYYMMDD 형식O
이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_idString사용자 IDO
target_id_typeStringtarget_id 타입
user_id: 회원번호
account_id: 카카오계정 ID
talk_id: 카카오톡 회원번호
O
ciString서비스에서 자체 본인인증으로 획득한 사용자의 CIO
birth_dateString사용자의 생년월일, YYYYMMDD 형식O
이름타입설명필수
idLong회원번호O
account_idInteger카카오계정 ID

제공 조건: 카카오계정 ID 응답 권한 보유
X
is_registrableBoolean본인인증 정보 등록 가능 여부
  • true: 등록 가능
  • false: 등록 불가능
O
  • 파라미터
    • CI(ci)
    • 생년월일(birth_date)
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)
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로 등록 실패인 경우, 공동체 앱: 본인인증 정보 등록 가능 여부 조회로 등록 가능 여부를 재확인해야 합니다.

카카오계정에 본인인증 정보 등록은 2022년 3월 8일부터 새로운 버전으로 제공합니다. 신규 버전은 API의 용도를 보다 직관적으로 이해하고 사용할 수 있도록 변경되었습니다. 기존 버전인 /v1/internal/user/collect/auth_info의 정보는 링크에서 확인할 수 있습니다.

이름설명필수
AuthorizationAuthorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
이름타입설명필수
ciString서비스에서 자체 본인인증으로 획득한 사용자의 CIO
birth_dateString사용자의 생년월일, YYYYMMDD 형식O
auth_typeString인증 유형, 본인인증기관 및 본인인증방식, 아래 중 하나
  • DANAL_PHONE
  • DANAL_SMS
  • DREAMSECURITY_SMS
  • KCB_CREDIT
  • KMC_SMS
  • NICE_NAME
  • SCI_SMS
O
이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_idString사용자 IDO
target_id_typeStringtarget_id 타입
user_id: 회원번호
account_id: 카카오계정 ID
talk_id: 카카오톡 회원번호
O
ciString서비스에서 자체 본인인증으로 획득한 사용자의 CIO
birth_dateString사용자의 생년월일, YYYYMMDD 형식O
auth_typeString인증 유형, 본인인증기관 및 본인인증방식, 아래 중 하나
  • DANAL_PHONE
  • DANAL_SMS
  • DREAMSECURITY_SMS
  • KCB_CREDIT
  • KMC_SMS
  • NICE_NAME
  • SCI_SMS
O
이름타입설명필수
idLong회원번호O
account_idInteger카카오계정 ID

제공 조건: 카카오계정 ID 응답 권한 보유
X
registeredBoolean본인인증 정보 등록 완료 여부
  • true: 등록 성공

참고: 본인인증 정보 등록에 실패한 경우 false 값이 아닌 -410 에러 응답 반환
O
  • 파라미터
    • CI(ci)
    • 생년월일(birth_date)
    • 인증기관 및 타입(auth_type)
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)
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을 반환하며 응답 바디는 없습니다.

카카오계정에서 본인인증 정보 삭제는 2022년 3월 8일부터 새로운 버전으로 제공합니다. 신규 버전은 API의 용도를 보다 직관적으로 이해하고 사용할 수 있도록 변경되었습니다. 기존 버전인 /v1/internal/user/delete/auth_info의 정보는 링크에서 확인할 수 있습니다.

이름설명필수
AuthorizationAuthorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_idString사용자 IDO
target_id_typeStringtarget_id 타입
user_id: 회원번호
account_id: 카카오계정 ID
talk_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)
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)를 반환합니다.

이름설명필수
AuthorizationAuthorization: Bearer ${ACCESS_TOKEN}
인증 방식, 액세스 토큰으로 인증 요청
O
이름타입설명필수
ciString서비스에서 자체 본인인증으로 획득한 사용자의 CIO
birth_dateString사용자의 생년월일, YYYYMMDD 형식O
이름설명필수
AuthorizationAuthorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}
인증 방식, 서비스 앱 어드민 키로 인증 요청
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_idString사용자 IDO
target_id_typeStringtarget_id 타입
user_id: 회원번호
account_id: 카카오계정 ID
talk_id: 카카오톡 회원번호
O
ciString서비스에서 자체 본인인증으로 획득한 사용자의 CIO
birth_dateString사용자의 생년월일, YYYYMMDD 형식O
이름타입설명필수
idLong회원번호O
account_idInteger카카오계정 ID

제공 조건: 카카오계정 ID 응답 권한 보유
X
is_matchedBoolean본인인증 정보 일치 여부
  • true: 요청 시 전달된 본인인증 정보가 카카오계정의 본인인증 정보와 일치
  • false: 요청 시 전달된 본인인증 정보가 카카오계정의 본인인증 정보와 일치하지 않거나, 카카오계정에 본인인증 정보 없음
O
  • 파라미터: 없음
    • CI(ci)
    • 생년월일(birth_date)
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)
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
}

도움이 되었나요?