사용자 관리

사용자 관리는 카카오 플랫폼 서비스에서 제공하는 핵심 기능 중 하나입니다. 사용자 관리는 쉽고 빠른 방법으로 사용자의 계정을 카카오 플랫폼과 연결해줍니다. 해당 기능을 통하여 안전하고 보다 더 강력한 참여형 사용환경의 앱을 만들 수 있습니다.

사용자 관리의 상세 기능은 다음과 같습니다.

  • 로그인
    카카오계정을 통한 빠르고 간편한 로그인 기능을 지원합니다.
  • 로그아웃
    로그인된 사용자의 세션 연결을 해제합니다.
  • 앱 연결
    로그인한 사용자와 앱을 카카오 플랫폼에 연결합니다. 사용자가 앱 가입/등록 요청을 하는 경우와 비슷합니다.
  • 앱 연결 해제
    카카오 플랫폼에 연결된 사용자와 앱의 연결을 영구 해제합니다. 사용자가 앱 탈퇴 요청을 하는 경우와 비슷합니다.
  • 사용자 정보 요청
    사용자에 대한 정보를 얻어 올 수 있습니다. 해당 기능을 사용하기 위해서는 로그인 및 앱 연결이 되어 있어야 합니다.
  • 사용자 정보 저장
    사용자에 대한 특정 정보를 저장할 수 있습니다. 해당 기능을 사용하기 위해서는 로그인 및 앱 연결이 되어 있어야 합니다.
  • 사용자 ID 리스트 요청
    앱 사용자들의 리스트를 얻어 올 수 있습니다. 해당 기능은 어드민 키(Admin Key)를 이용해 호출해야 합니다.
  • 사용자 토큰 유효성 검사 및 정보 얻기
    로그인을 통해 얻은 사용자 토큰(Access Token)의 유효성을 검사하거나 부가 정보를 얻을 수 있습니다.
  • 동적동의
    API 사용 시 사용자의 추가 동의가 필요한 경우 동적동의 과정이 필요합니다.

    로그인 API를 사용할 때 필요한 버튼은 여기를 참조하세요.

로그인

카카오계정을 이용하여 빠르고 간편하게 로그인을 할 수 있습니다.

해당 로그인 기능은 OAuth 2.0을 지원합니다. 다음은 카카오 플랫폼 서비스에서 제공하는 가장 일반적인 OAuth 인증의 과정입니다.

  1. 사용자는 카카오계정으로 로그인 버튼을 클릭합니다.
  2. 카카오톡 앱에 연결된 카카오계정의 자격정보(Credentials)를 통해 사용자를 인식합니다.
  3. 자격정보가 올바르다면 사용자(Resource Owner)로부터 접근 자원에 대한 동의/허가를 얻습니다.
  4. 위 3까지 성공적으로 수행되었다면 인증 코드(Authorization Code)가 발급됩니다. 해당 인증 코드는 Redirection URI를 기반으로 Third 앱에 전달됩니다.
  5. Third 앱에서는 전달받은 인증 코드를 기반으로 사용자 토큰(Access Token, Refresh Token)을 요청하고 얻게 됩니다.

    사용자 토큰은 카카오 플랫폼 서비스에서 제공하는 로그인 기반의 기능을 사용하는데 있어 중요한 키로 사용됩니다. OAuth 2.0의 보다 자세한 내용은 여기를 참고하세요.

코드 받기

로그인 버튼 클릭시 먼저 사용자 동의를 거쳐 토큰을 발급 받을 수 있는 코드를 받아와야 합니다.

카카오계정으로 로그인을 위한 버튼의 다양한 이미지는 여기에서 다운로드 할 수 있습니다.

[Request]

GET /oauth/authorize?client_id={app_key}&redirect_uri={redirect_uri}&response_type=code HTTP/1.1
Host: kauth.kakao.com
설명 필수
client_id 앱 생성시 발급 받은 REST API 키. O
redirect_uri 코드를 리다이렉트 해줄 URI.
설정 > 일반 > > 사이트 도메인 에서 설정한 각각의 도메인에 설정 > 일반 > > Redirect Path 를 붙인 URI.
O
response_type code 문자열 값으로 고정. O
state 로그인 이전 상태를 유지하기 위해 저장하는 값. 결과가 리다이렉트 될 때 입력한 state 값이 그대로 전달됨. Cross-site Request Forgery 공격을 보호하기 위해 활용 가능. X
encode_state state 파라미터를 사용하고자 하는 경우 true로 고정. (1 또는 y 허용) X

redirect_uri의 예는 다음과 같습니다. 예를 들어, 사이트 도메인으로 http://your.website.domain.com을, Redirect Path로 "/kakao_oauth"를 설정하였다면 redirect_uri는 http://your.website.domain.com/kakao_oauth 형식이 됩니다. Redirect Path의 기본값은 "/oauth" 입니다.

해당 기기에서 카카오계정으로 로그인이 된 적이 없다면 로그인 창으로 리다이렉트 됩니다. 한번 로그인한 카카오계정은 6시간 동안 유효함으로 6시간 이내에 로그인 한 적이 있다면 바로 접근 자원에 대한 동의/허가를 위한 화면이 나타납니다.

[Response]

허용을 클릭하면 코드를 쿼리 스트링으로 담아 redirect_uri로 리다이렉트 합니다. redirect_uri 요청에 대해 처리하여 code를 얻도록 합니다.

HTTP/1.1 302 Found
Content-Length: 0
Location: {redirect_uri}?code={authorize_code}

사용자 토큰 받기

코드를 얻은 다음, 이를 이용하여 실제로 API를 호출할 수 있는 사용자 토큰(Access Token, Refresh Token)을 받아 올 수 있습니다.

[Request]

POST /oauth/token HTTP/1.1
Host: kauth.kakao.com

아래 파라미터의 값들을 POST로 요청합니다.

설명 필수
grant_type authorization_code로 고정 O
client_id 앱 생성시 발급 받은 REST API 키. O
redirect_uri 코드가 리다이렉트 된 URI.
설정 > 일반 > > 사이트 도메인에서 설정한 각각의 도메인에 설정 > 일반 > > Redirect Path 를 붙인 URI.
O
code 코드 받기에서 발급 받은 인증된 코드. O
client_secret 설정 > 일반 > Client Secret 에서 생성한 client_secret 코드
ACTIVE 상태 인 경우 필수로 설정해야 함
X

예를들어 다음과 같이 POST로 요청합니다.

curl -v -X POST https://kauth.kakao.com/oauth/token \
 -d 'grant_type=authorization_code' \
 -d 'client_id={app_key}' \
 -d 'redirect_uri={redirect_uri}' \
 -d 'code={authorize_code}'

[Response]

응답 바디는 JSON 객체로 아래 값을 포함합니다.

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "access_token":"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "token_type":"bearer",
    "refresh_token":"yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy",
    "expires_in":43199,
    "scope":"Basic_Profile"
}

요청 결과로 API를 호출할 때 사용하는 access_token과 해당 토큰의 만료 시간(초 단위), 또한 토큰을 갱신 할 수 있는 refresh_token을 받습니다.

사용자 토큰 갱신

토큰이 만료되면, 토큰 요청 응답으로 받은 또는 토큰 갱신 요청 응답으로 받은 refresh_token을 이용하여 토큰을 갱신합니다.

access_token은 발급 받은 후 12시간-24시간(정책에 따라 변동 가능)동안 유효합니다. refresh token은 한달간 유효하며, refresh token 만료가 1주일 이내로 남은 시점에서 사용자 토큰 갱신 요청을 하면 갱신된 access token과 갱신된 refresh token이 함께 반환됩니다.

토큰을 갱신하기 위해서는 아래 요청이 필요합니다.

[Request]

POST /oauth/token HTTP/1.1
Host: kauth.kakao.com

아래 파라미터의 값들을 POST로 요청합니다.

설명 필수
grant_type refresh_token로 고정 O
client_id 앱 생성시 발급 받은 REST API 키. O
refresh_token 토큰 발급시 응답으로 받은 refresh_token으로 Access Token을 갱신하기 위해 사용된다. O
client_secret 설정 > 일반 > Client Secret 에서 생성한 client_secret 코드
ACTIVE 상태 인 경우 필수로 설정해야 함
X

예를들어 다음과 같이 POST로 요청합니다.

curl -v -X POST https://kauth.kakao.com/oauth/token \
 -d 'grant_type=refresh_token' \
 -d 'client_id={app_key}' \
 -d 'refresh_token={refresh_token}'

[Response]

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "access_token":"wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww",
    "token_type":"bearer",
    "refresh_token":"zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",  //optional
    "expires_in":43199,
}

요청 결과로 갱신된 새로운 access_token과 해당 토큰의 만료 시간, 또한 Refresh Token 자체가 갱신되었으면 갱신된 refresh_token도 함께 받게 됩니다. refresh_token은 응답에 포함될 수도 있고 포함되지 않을 수도 있기 때문에 포함된 경우에 대해서만 갱신하여 저장하도록 합니다.

로그아웃

카카오계정과의 세션 연결을 해제하는 기능입니다.

로그인 기능은 멀티디바이스를 지원합니다. 만약 사용자가 여러 기기에서 하나의 같은 카카오계정으로 로그인 후 로그아웃을 수행한다면, 해당 로그아웃을 수행한 기기에서만 세션 연결이 해제됩니다.

[Request]

POST /v1/user/logout HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}

사용자 토큰을 헤더에 담아 POST로 요청합니다. 예를 들면,

curl -v -X POST https://kapi.kakao.com/v1/user/logout \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

[Response]

응답 바디는 JSON 객체로 아래 값을 포함합니다.

설명 타입
id 로그아웃된 사용자 ID signed int64

예를 들면,

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":123456789
}

앱 연결

앱 연결은 로그인한 사용자와 앱을 카카오 플랫폼에 연결함으로서 일반적으로 사용자가 앱 가입/등록 요청을 하는 경우와 비슷합니다. 카카오 플랫폼 서비스를 올바로 사용하기 위해서는 로그인 후 반드시 앱 연결이 선행되어야 하며, 최초 한번만 수행가능합니다. 앱 연결이 올바로 수행되면 해당 사용자에 대한 고유한 사용자 아이디(ID)가 부여됩니다.

로그인 수행 후, 사용자 정보를 호출하였으나 가입이 안된 상태라 실패한다면 가입 창을 띄워줘야 합니다. 가입 시 개별 사용자에 대한 특정 부가정보를 저장하고 싶은 경우 가입과 함께 사용자 정보를 저장할 수 있습니다. 이는 가입 후에 사용자 정보 저장을 통해 업데이트 될 수 있습니다.

[Request]

POST /v1/user/signup HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
Content-Type: application/x-www-form-urlencoded;charset=utf-8

사용자 토큰을 헤더에 담아 POST로 요청합니다. 앱 연결과 동시에 사용자 정보를 저장하고 싶은 경우, 사용자 토큰과 함께 아래 파라미터의 값들을 POST로 요청할 수 있습니다. 사용자 정보는 가입 후 사용자 정보 저장을 통해 업데이트 될 수 있습니다.

설명 필수
properties 가입하는 사용자의 정보. JSON 형태의 key-value. X

예를 들어, 가입시 사용자의 나이와 성별을 받고자 한다면 아래와 같이 요청합니다.

age와 gender는 사용자 관리 설정에서 커스텀 사용자 정보 컬럼으로 추가되어 있어야 합니다.

curl -v -X POST https://kapi.kakao.com/v1/user/signup \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode 'properties={"age":"23", "gender":"female"}'

[Response]

앱 연결 요청이 성공하면 응답 바디에 JSON 객체로 아래 값을 포함합니다.

설명 타입
id 앱연결된 사용자 ID signed int64

예를 들면,

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":123456789
}

앱 연결 해제

앱 연결 해제는 카카오 플랫폼에 연결된 사용자와 앱의 연결을 영구 해제함으로서 일반적으로 사용자가 앱 탈퇴 요청을 하는 경우와 비슷합니다. 앱 연결 해제가 수행된 사용자는 영구적으로 복구가 불가능하며 카카오 플랫폼 서비스를 더이상 사용할 수 없습니다. 단, 다시 앱 연결을 통해 새로운 데이타로 카카오 플랫폼 서비스를 이용할 수는 있습니다.

앱 연결 해제를 수행할 경우 카카오 플랫폼에서 관리하는 해당 사용자의 데이타는 모두 지워집니다. 단, Third앱에서 저장하는 데이타의 경우 카카오 플랫폼 서비스에서는 책임을 질 수 없습니다. 이는 Third앱에서 지워야 할 의무를 가집니다(보다 자세한 내용은 정책 및 약관을 참고하세요). 이것이 흔히 말하는 앱 탈퇴와 앱 연결 해제와의 차이점입니다.

사용자가 Third앱 탈퇴시와 카카오계정과의 연결 해제를 원할 시, 앱연결 해제를 호출해 주셔야 합니다. 카카오계정과의 앱 연결 해제는 Third앱이 아니라, 카카오계정 서비스에서도 발생할 수 있습니다. 서비스 외부에서 해당 서비스와 카카오계정 연결 해제시 콜백을 받을 수 있습니다. 설정은 여기를 참고하세요.

[Request]

POST /v1/user/unlink HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
POST /v1/user/unlink HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {admin_key}

어드민 키(Admin Key)는 절대로 유출되어서는 안 되는, 일종의 마스터 키(Master Key)이므로 반드시 Third 서버에서 API를 호출해야 합니다. 어드민 키는 카카오 웹사이트의 내 애플리케이션에서 확인할 수 있습니다. 만약 iOS, Android 애플리케이션의 소스코드 내에서 어드민 키를 사용할 경우, 해당 애플리케이션은 보안에 취약할 수 있습니다.

사용자 토큰/어드민키를 헤더에 담아 POST로 요청합니다.

curl -v -X POST https://kapi.kakao.com/v1/user/unlink \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
curl -v -X POST https://kapi.kakao.com/v1/user/unlink \
  -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkk" \
  -d 'target_id_type=user_id&target_id=123456789'

[Response]

앱 연결 해제 요청이 성공하면 응답 바디에 JSON 객체로 아래 값을 포함합니다.

설명 타입
id 앱 연결 해제된 사용자 ID signed int64

예를 들면,

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":123456789
}

사용자 정보 요청

v2 API로 업데이트 되었습니다. 기존 v1 API를 사용했다면 v1 사용자 정보 요청과 달라진 점를 확인하시고 업데이트 해주세요.

사용자 정보 요청은 사용자에 대한 아이디(ID) 와 카카오계정 이메일(email) 및 개별 상세 정보를 얻어 올 수 있는 기능입니다. 해당 기능을 사용하기 위해서는 성공적인 로그인 후에 얻을 수 있는 사용자 토큰이 필요합니다. 또한 앱 연결이 전제가 되어 있어야 합니다.

사용자 아이디(ID)의 경우 앱 연결 과정에서 발급하는 앱별 사용자의 고유 아이디입니다. 해당 아이디를 통해 사용자를 앱에서 식별 가능하며, 카카오계정을 탈퇴하지 않는 한 해당 서비스 내에서 같은 사용자는 같은 값으로 계속 유지됩니다. 단, 2018년 9월 19일 이전에 사용자 관리를 사용 중이던 서비스는 이전 정책에 따라 앱 연결 해제 시까지만 같은 값이 유지됩니다. '설정 > 사용자 관리 > 사용자 아이디 고정' 메뉴에서 정책 적용 여부를 확인할 수 있습니다.

카카오계정 이메일을 수집하여 사용할때 다음 내용을 주의하세요.

  • 사용자의 카카오계정 이메일이 없을 수 있습니다.

    모든 사용자에 대해 이메일이 필요한 서비스라면, 이메일 소유여부를 확인하세요. 카카오계정 이메일이 없는 경우에는, 서비스에서 사용자에게 카카오계정 이메일이 없음을 안내하고 사용자로부터 직접 이메일을 입력받는 방법을 권장합니다. (예. 카카오계정에 이메일이 존재하지 않습니다. 이메일주소 입력이 필요합니다.)

  • 사용자의 카카오계정 이메일은 인증 받지 않은 이메일일 수 있습니다.

    인증받은 이메일만 사용하는 서비스라면, 이메일 인증여부를 확인하세요. 인증받지 않은 카카오계정 이메일을 사용하는 사용자의 경우에는, 서비스에서 사용자에게 카카오계정 이메일이 인증받지 않았음을 안내하고 사용자로부터 직접 이메일을 입력받는 방법을 권장합니다.(예. 인증받지 않은 카카오계정을 사용중입니다. 이메일주소 입력이 필요합니다.)

  • 카카오계정의 이메일은 사용자의 요청으로 인해 변경 될 수 있습니다. 서비스에서는 이메일을 활용하는 시점에 이메일의 변경 유무를 확인할 것을 권장합니다.

관리자가 특정 사용자의 정보를 얻어내고자 할 때는 어드민 키와 사용자 ID를 통해서도 요청할 수 있습니다.

해당 기능을 사용하기 위해서는 앱 사용자 전체를 관리 할 수 있는 어드민 키(Admin Key)가 필요합니다. 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 자체 앱 서버에서 API를 호출하시기 바랍니다.

[Request]

GET/POST /v2/user/me HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
Content-type: application/x-www-form-urlencoded;charset=utf-8
GET/POST /v2/user/me HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {admin_key}
Content-type: application/x-www-form-urlencoded;charset=utf-8

어드민 키(Admin Key)는 절대로 유출되어서는 안 되는, 일종의 마스터 키(Master Key)이므로 반드시 Third 서버에서 API를 호출해야 합니다. 어드민 키는 카카오 웹사이트의 내 애플리케이션에서 확인할 수 있습니다. 만약 iOS, Android 애플리케이션의 소스코드 내에서 어드민 키를 사용할 경우, 해당 애플리케이션은 보안에 취약할 수 있습니다.

어드민 키와 사용자 아이디(ID)를 인증정보로 사용할 경우 아래 파라미터와 함께 요청합니다.

설명 필수
target_id_type 사용자 아이디의 타입. user_id로 고정된 값 O
target_id 사용자 아이디(ID) O

사용자 토큰 또는 어드민키와 사용자 아이디(ID)를 헤더에 담아 GET/POST로 요청합니다. 사용자 인증정보와 함께 아래 파라미터의 값을 선택적으로 추가할 수 있습니다.

설명 필수
property_keys 사용자 정보의 키 리스트. JSON Array 형태. X
secure_resource 이미지 url을 https로 반환할지 여부. true/false X

property_keys로 요청할 수 있는 키 리스트입니다.

설정 > 사용자 관리 > 사용자 목록 및 프로퍼티 관리 에서 추가로 등록한 프로퍼티도 사용할 수 있습니다.

Name Description
properties.nickname 카카오톡 또는 카카오스토리의 닉네임 정보
properties.profile_image 640px * 640px 크기의 프로필 이미지 URL (2017/08/22 이전 가입자에 대해서는 480px * 480px ~ 1024px * 1024px 크기를 가질 수 있음)
properties.thumbnail_image 110px * 110px 크기의 썸네일 프로필 이미지 URL (2017/08/22 이전 가입자에 대해서는 160px * 213px 크기를 가질 수 있음)
kakao_account.email 사용자 카카오계정의 이메일 소유여부, 이메일 값, 이메일 인증여부, 이메일 유효여부
kakao_account.age_range 사용자 카카오계정의 연령대 소유여부, 연령대 값
kakao_account.birthday 사용자 카카오계정의 생일 소유여부, 생일 값
kakao_account.gender 사용자 카카오계정의 성별 소유여부, 성별 값

예를 들어 사용자 전체 정보를 얻고 싶다면 아래와 같이 요청합니다.

curl -v -X GET https://kapi.kakao.com/v2/user/me \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

예를 들어 사용자 정보 중 이메일정보만 얻고 싶다면 아래와 같이 요청합니다.

curl -v -X POST https://kapi.kakao.com/v2/user/me \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d 'property_keys=["kakao_account.email"]'

해당 앱의 서버에서 사용자 아이디(ID)가 12345인 사용자의 이메일정보만 얻고 싶다면 아래와 같이 요청합니다.

curl -v -X POST https://kapi.kakao.com/v2/user/me \
  -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkk" \
  -d 'target_id_type=user_id&target_id=12345' \
  -d 'property_keys=["kakao_account.email"]'

[Response]

사용자 정보 요청이 성공하면 응답 바디에 JSON 객체로 아래 값을 포함합니다.

설명 타입
id 유저의 고유 ID signed int64
properties 사용자의 정보. Json 형태의 key-value.
사용자 정보 키를 지정한 경우는 해당 키에 대한 정보만 포함 합니다.
String
kakao_account.has_email 카카오계정의 이메일 소유 여부. 전화번호로 카카오계정을 생성하고, 추후에도 이메일 입력을 하지 않은 카카오계정인 경우 이메일이 존재하지 않습니다. has_email=false인 경우 is_email_valid,is_email_verified, email 값은 응답에 포함되지 않습니다. Boolean
kakao_account.is_email_valid 카카오계정의 이메일 유효 여부. 간혹 이메일 실소유자에 의해 카카오계정 이메일이 무효화 되는 경우 값이 false로 내려갑니다. Boolean
kakao_account.is_email_verified 인증받은 카카오계정 이메일인지 여부 Boolean
kakao_account.email 사용자 카카오계정의 이메일
- 카카오계정 이메일은 변경될 수 있습니다.
- 이메일 개인정보 제공동의를 하지 않은 사용자의 이메일은 제공되지 않습니다. has_email=true인데 email값이 내려오지 않는다면, 사용자가 정보제공 동의를 하지 않은 경우입니다.
String
kakao_account.has_age_range 카카오계정의 연령대 소유 여부.
- has_age_range=false인 경우 age_range 값이 내려가지 않습니다.
Boolean
kakao_account.age_range 사용자 카카오계정의 연령대. 15~19/20~19/30~39 ... 80~89/90~ String
kakao_account.has_birthday 카카오계정의 생일 소유 여부.
- has_birthday=false인 경우 birthday 값이 내려가지 않습니다.
Boolean
kakao_account.birthday 사용자 카카오계정의 생일. MMDD 형식 String
kakao_account.has_gender 카카오계정의 성별 소유 여부.
- has_gender=false인 경우 gender 값이 내려가지 않습니다.
Boolean
kakao_account.gender 사용자 카카오계정의 성별. female/male String

기본으로 제공되는 사용자 프로퍼티로는 nickname, profile_image, thumbnail_image가 있습니다.

  • nickname: 카카오톡 또는 카카오스토리의 닉네임 정보
  • profile_image: 640px * 640px 크기의 카카오톡 또는 카카오스토리의 프로필 이미지 URL (2017/08/22 이전 가입자에 대해서는 480px * 480px ~ 1024px * 1024px 크기를 가질 수 있음)
  • thumbnail_image: 110px * 110px 크기의 카카오톡 또는 카카오스토리의 썸네일 프로필 이미지 URL (2017/08/22 이전 가입자에 대해서는 160px * 213px 크기를 가질 수 있음)
HTTP/1.1 200 OK
{
  "id":123456789,
  "properties":{
     "nickname":"홍길동",
     "thumbnail_image":"http://xxx.kakao.co.kr/.../aaa.jpg",
     "profile_image":"http://xxx.kakao.co.kr/.../bbb.jpg",
     "custom_field1":"23",
     "custom_field2":"여"
     ...
  },
  "kakao_account": { 
    "has_email": true, 
    "is_email_valid": true,   
    "is_email_verified": true,   
    "email": "xxxxxxx@xxxxx.com"
    "has_age_range":true,
    "age_range":"20~29",
    "has_birthday":true,
    "birthday":"1130",
    "has_gender":true,
    "gender":"female"
  }
}


카카오계정의 이메일, 연령대, 생일, 성별을 활용하기전에 확인하세요!

하나, 설정 > 사용자 관리 > 동의항목 에서 '개인정보 보호항목'에 이메일/연령대/생일/성별 보이는지 확인합니다.
보이지 않는다면, 수집목적을 작성하고 필요한 항목을 설정합니다.

둘, 응답에 hasXXX 값으로 해당값을 소유 여부를 확인합니다.
hasXXX 값이 false이면 해당 사용자는 카카오계정에 해당값을 소유하지 않은 것은 것으로 판단합니다.
hasXXX 값이 true인데, 해당값이 응답에 포함되어 있지 않다면, 사용자가 해당 항목에 대해 개인정보 제3자 제공 동의를 하지 않는 경우 입니다.
해당값의 동의항목을 scope에 전달하여 동적동의를 사용자에게 받은 후, 사용자 정보 요청을 다시 합니다.

response key 동적동의 요청시 scope
email account_email
age_range age_range
birthday birthday
gender gender

v1 사용자 정보 요청과 달라진 점
  • 자동가입이 off일때 토큰발급만 받고, 명시적으로 앱 연결은 호출 안한 상태에서 v1 사용자 정보 요청시 NotRegisteredException발생했지만, v2 사용자 정보 요청시에는 발생하지 않습니다.
  • 특정 property만 가지고 가고 싶을때 사용하는 파라미터 이름이 변경되었습니다. propertyKeys -> property_keys
  • response의 키 중 kaccount prefix를 가진 키는 kakao_account 하위로 계층이 생겼습니다.
  • 연령대, 생일, 성별 값이 추가 되었습니다.
  • 추가 동의가 필요한 이메일, 연령대, 생일, 성별의 경우 hasXXX 응답이 추가 되었습니다.
  • response의 값이 존재하지 않으면, 키도 내려가지 않습니다.
  • 서버가 불안정한 경우, kakao_account 하위의 값을 가지고 오지 못하더라도 에러를 발생시키지 않습니다. 꼭 필요한 경우는 재요청을 하셔야 합니다.

사용자 정보 저장

사용자 정보 저장은 개별 사용자에 대한 특정 부가정보를 저장할 수 있는 기능입니다. 카카오 플랫폼 서비스에서 제공하는 기본 부가정보 외에도, 개발자 웹사이트를 통해 앱별 커스텀한 정보를 선언하여 유저별 데이타를 저장할 수 있습니다. 해당 기능을 사용하기 위해서는 성공적인 로그인 후에 얻을 수 있는 사용자 토큰이 필요합니다. 또한 앱 연결이 전제가 되어 있어야 합니다.

사용자 정보 저장 기능으로 수정할 수 없는 사용자의 정보도 존재합니다. 예를 들어 사용자의 아이디(ID)는 수정될 수 없습니다.

profile_image와 thumbnail_image 둘 중 하나만 저장 요청하여도 640px * 640px, 110px * 110px 크기로 각각 저장됩니다. 두 이미지를 함께 저장 요청한 경우 profile_image를 원본으로 각 크기로 저장됩니다.

[Request]

POST /v1/user/update_profile HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
Content-type: application/x-www-form-urlencoded;charset=utf-8

사용자 토큰과 함께 아래 파라미터의 값들을 POST로 요청합니다.

설명 필수
properties 가입하는 사용자의 정보. JSON 형태의 key:value. O

예를 들어, 사용자 정보에 기본 부가정보 중 nickname과 커스텀 정보 age을 갱신하고자 한다면 아래와 같이 요청합니다.

age와 gender는 사용자 관리 설정에서 커스텀 사용자 정보 컬럼으로 추가되어 있어야 합니다.

curl -v -X POST https://kapi.kakao.com/v1/user/update_profile \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --data-urlencode 'properties={"nickname":"홍길동","age":"22"}'

[Response]

사용자 정보 저장 요청이 성공하면 응답 바디에 JSON 객체로 아래 값을 포함합니다.

설명 타입
id 사용자 ID signed int64

예를 들면,

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":123456789
}

사용자 리스트 요청

해당 앱의 유저 ID 리스트를 페이징 형식으로 가져옵니다. 페이징은 전체 리스트를 여러번의 API 요청으로 분리하여 제공하는 방식입니다. 먼저 아무런 파라미터 값 없이 요청을 보내면, 유저 ID의 오름차순으로 1 ~ 100 번째 유저 ID 리스트 페이지가 나옵니다. 또한 결과값과 함께, 이전 페이지 URL과 다음 페이지 URL 이 포함되어있는데, 이전 페이지 URL 은 현재 페이지 전에 나와야 할 페이지 (현재 페이지에서 가장 작은 유저 ID보다 유저 ID가 작은 100명의 페이지)의 URL이고 다음 페이지 URL 은 현재 페이지 다음에 나와야 할 페이지 (현재 페이지에서 가장 큰 유저 ID보다 유저 ID가 큰 100명의 페이지)의 URL입니다. 만약 이전 페이지나 다음 페이지에 들어갈 유저가 없다면, URL에 null값이 리턴됩니다.

따라서, 전체 유저를 모두 얻고 싶다면 아래와 같은 단계로 진행하면 됩니다.

  1. 아무런 파라미터 값이 없는 요청을 한번 보냅니다.
  2. 받아온 결과에서 사용자자 ID들을 처리하고, 다음페이지 URL을 요청합니다.
  3. 2를 반복하다가 URL이 null이 리턴된 경우, 더이상 받아올 사용자가 없으므로 멈춥니다.

특수한 방식의 요청을 하고 싶으신 경우에는 아래의 from_id, limit, order를 이용해 'from_id보다 유저 ID가 큰/작은 순서로 limit명의 앱 유저 리스트'를 만들어 낼 수 있습니다.

해당 기능을 사용하기 위해서는 앱 사용자 전체를 관리 할 수 있는 어드민 키(Admin Key)가 필요합니다. 어드민 키가 탈취되는 일이 없도록 앱 내에서 직접 어드민 키로 API를 호출하지 않고, 자체 앱 서버에서 API를 호출하시기 바랍니다.

[Request]

GET /v1/user/ids HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {admin_key}
Content-type: application/x-www-form-urlencoded;charset=utf-8

어드민 키와 함께 아래 파라미터 값을 요청할 수 있습니다.

설명 필수
limit 페이지에 들어갈 최대 사용자 수. (최소 1명, 최대 100, 기본값 100) Integer 형태. X
from_id 페이징을 시작하는 기준이되는 유저 ID 값. 일반적으로 Response에서 나온 결과를 이용합니다. 값이 없을 경우 가장 작은 ID를 가진 유저부터 읽어옵니다. Long 형태 X
order 페이징을 검색하는 방향. asc / desc 중 하나 (기본값 asc) X

예를 들어, 첫 사용자 100명의 전체 정보를 얻고 싶다면 아래와 같이 요청합니다.

curl -v -X GET https://kapi.kakao.com/v1/user/ids \
  -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk"

유저 ID가 12345보다 큰 사용자 3명만 얻고 싶다면 아래와 같이 요청합니다.

curl -v -X POST https://kapi.kakao.com/v1/user/ids \
  -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkkkk" \
  -d 'limit=3&order=asc' \
  -d 'from_id=12345'

[Response]

사용자 정보 리스트트 요청이 성공하면 응답 바디에 JSON 객체로 아래 값을 포함합니다.

설명 타입
elements 유저들의 ID 리스트. List
total_count 앱의 총 사용자 수. Integer
before_url 이전 페이지 URL. 이전 페이지가 없을 경우 null. String
after_url 다음 페이지 URL. 다음 페이지가 없을 경우 null. String
HTTP/1.1 200 OK
{
  "elements": [
  1376016924426111111, 1376016924426222222, 1376016924426333333 ]
  , "total_count": 9
  , "before_url": "http://kapi.kakao.com/v1/user/ids?limit=3&order=desc&from_id=1376016924426111111&app_key=12345674ae6e12379d5921f4417b399e7"
  , "after_url": "http://kapi.kakao.com/v1/user/ids?limit=3&order=asc&from_id=1376016924426333333&app_key=12345674ae6e12379d5921f4417b399e7"
}

사용자 토큰 유효성 검사 및 정보 얻기

사용자 토큰 받기를 통해 얻은 Access Token의 유효성을 검사하거나 해당 토큰의 부가 정보를 얻습니다.

사용자 토큰 갱신을 위해서는 현재 가지고 있는 토큰이 만료 되었는지, 얼마동안 유효한지 등을 특정 주기안에서 호출해야 할 필요성이 있습니다.

사용자 토큰의 경우 Native SDK, REST API, Javascript SDK등을 통해 얻을 수 있습니다. 어느 플랫폼에서 얻은 사용자 토큰이든 관계없이, 로그인 후 얻은 사용자 토큰으로 주어진 기능을 사용할 수 있습니다.

[Request]

GET /v1/user/access_token_info HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {access_token}
Content-type: application/x-www-form-urlencoded;charset=utf-8

사용자 토큰을 요청 헤더에 담아 GET Method로 요청합니다. 다른 추가적인 파라미터는 필요없습니다.

다음은 해당 기능의 요청 예제입니다.

curl -v -X GET https://kapi.kakao.com/v1/user/access_token_info \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

[Response]

요청이 성공하면 응답 바디에 JSON 객체로 아래 값을 포함합니다.

설명 타입
id 사용자 ID signed int64
expiresInMillis 주어진 토큰의 남은 유효기간(Milli-seconds). 0 또는 양수 signed int64
appId 주어진 토큰을 발급한 앱의 id signed int64
HTTP/1.1 200 OK
{
    "id":123456789,
    "expiresInMillis":239036,
    "appId":1234
}

위의 응답은 주어진 토큰이 올바를 경우에 대한 예제입니다. 만약 주어진 사용자 토큰이 잘못된 형식일 경우 HTTP Status 400에 code -2가 반환될 수 있으며, 이미 토큰이 만료되었을 경우 HTTP Status 401에 code -401이 반환될 수 있습니다.

응답 에러 코드가 -401일 경우(보통 토큰 만료일 경우), 일반적으로 호출한 곳에서 사용자 토큰 갱신을 해 주어야 합니다. 응답 에러 코드가 -1일 경우 카카오 플랫폼 서비스의 일시적 내부 장애 상태이므로, 토큰을 강제 만료(폐기) 또는 로그아웃 처리를 하지 않는 것이 좋습니다(일시 장애 메시지 처리를 권장합니다). 그 외의 에러는 앱/사용자/토큰 등의 상태가 더이상 유효하지 않는 경우이므로, 토큰 재갱신을 하여도 큰 의미는 없습니다. 이 경우는 로그아웃 처리를 권장합니다.

자세한 에러에 대한 정보는 에러 코드를 참고하세요.

동적동의

API 사용 시 사용자의 추가 동의가 필요한 경우 동적동의 과정이 필요합니다.

예를 들어 카카오톡 메시지 전송에 대한 동의를 하지않은 사용자가 나에게 보내기 요청합니다.

curl -v -X POST 'https://kapi.kakao.com/v2/api/talk/memo/default/send' \
-H 'Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
-d 'template_object={...}'

[Response]

요청이 실패하면서 응답 바디에 JSON 객체로 아래 값을 포함합니다.

설명
required_scopes 현재 API를 사용하기 위해서 필요한 동의항목
allowed_scopes 사용자가 동의한 동의항목
HTTP/1.1 403 Forbidden
{
  "msg": "insufficient scopes.",
  "code": -402,
  "api_type": "TALK_MEMO_DEFAULT_SEND",
  "required_scopes": [
    "talk_message"
  ],
  "allowed_scopes": [
    "profile",
    "account_email"
  ]
}

API 응답의 required_scopes를 포함해서 동적동의를 요청해야 합니다.

[Request]

GET /oauth/authorize?client_id={app_key}&redirect_uri={redirect_uri}&response_type=code&scope={required_scopes.join(',')} HTTP/1.1
Host: kauth.kakao.com
설명 필수
scope API 요청 시 응답으로 받은 required_scopes
","로 합쳐서 전달합니다.
O

동적동의 과정은 코드 받기 과정과 동일합니다. 코드 받기을 참고해 주세요.


Last Modified : 2018-10-04