User management

User management is core functionality provided by kakao platform service. User management connects user's account with kakao platform easliy. You can now make secure and user interactive app easily.

Details on functionality of user management follows.

  • Login: Support easy and fast login through kakao account.
  • Logout: Disconnect user login session.
  • Connecting App: Connect logged in user and app to kakao platform. This is similar procedure to user registering app.
  • Disconnecting App: Disconnect connection of user and app to kakao platform permanently. This is similar to request for unregistering user.
  • User information retrieval: Possible to retrieve user information. In order to use such functionality,login and app must be connected.
  • Saving user information: Possible to save specific user information.In order to use such functionality,login and app must be connected.
  • Requesting user ID list: You can retrieve app user list. Such functionality must be called using Admin Key.
  • Validating and getting information from user token: You can validate user token(access token) and get additional information about the token.
  • Dynamic approval: If additional user approval is required when using API, you need a dynamic approval process.

    When using login API, refer here.

Login

You can login with kakao account.

Following login support OAuth 2.0. Following is an general way of using OAuth authentication method, provided by kakao platform service.

  1. User clicks on kakao account login.
  2. Use Credentials saved in Kakao talk to login user.
  3. If the credential is correct, Resource Owner must grant permission to use information.
  4. If above 3 cases have successfully accomplished, Authorization Code will be granted. Such authorization code is based on Redirection URI and will be sent to the Third app.
  5. Using authorization code, retrieved from Third app, Access Token and Refresh Token will be requested and obtained.

    User token is the most important factor for using login based service in kakao platform. For details on OAuth 2.0, refer here.

Code retrieval

Code for retrieving token must be retrieved after clicking on login button and permission has been granted.

Kakao account login button image can be downloaded here.

[Request]

GET /oauth/authorize?client_id={app_key}&redirect_uri={redirect_uri}&response_type=code HTTP/1.1
Host: kauth.kakao.com
Key description required
client_id REST API Key, retrieved when creating an APP. O
redirect_uri Redirection URI for code.
each domains included URI in setting > general > web > Redirect Path, set from setting > general > web > site domain.
O
response_type fixed to code character. O
state An opaque value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. The parameter may be used for preventing Cross-site Request Forgery. X
encode_state Set to true if you want to use the state parameter. (1 or y allowed) X

redirect_uri described as following. For example, if site domain "http://your.website.domain.com", has set Redirect Path to "/kakao_oauth", redirect_uri will be of form "http://your.website.domain.com/kakao_oauth". Redirect Path's default value is "/oauth".

If current device has never logged in with kakao account, it will be redirected to login window. Kakako account logged in once will remain for 6hours and if it's still valid to login within six hours, window for agreement/permission will pop-up.

[Response]

If permission was granted by clicking the button, it will be redirected to redirect_uri with code included in query string.

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

Retrieving user token

After code has been obtained,Access Token, Refresh Token for requesint API can be obtained.

[Request]

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

Request through POST method with below parameter.

Key description required
grant_type set to authorization_code O
client_id REST API retrieved upon app creation. O
redirect_uri each domains included URI in setting > general > web > Redirect Path, set from setting > general > web > site domain. O
code Authorized code from code retrieval. O
client_secret 설정 > 일반 > Client Secret 에서 생성한 client_secret 코드
ACTIVE 상태 인 경우 필수로 설정해야 함
X

dev_011.png

예를들어 다음과 같이 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]

Response body will include JSON object as below.

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"
}

With such access_token retrieved as result, which can be used for requesting API, will include time for when it expires and refresh_token for refreshing the token when needed.

Refresh user token

If token expires, token can be refreshed using the refresh_token obtained as response for requesting token.

After access_token has been granted, it will remain valid for 12-24 (Depending on policy)hours. refresh token is valid for two months, and refresh token can be renewed prior to 1 month of expiration date, which will return newly created access token and refresh token on request.

In order to refresh a token, below request is needed.

[Request]

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

Below parameter values must be requested in POST method.

Key description required
grant_type set to refresh_token O
client_id REST API key issued upon creation of an app. O
refresh_token When issuing token, refresh token will be used for refreshing a new 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,
}

New access_token and token expiration time will be received as request result. If the token has been refreshed with new expiration time, new Refresh token will be received upon request. refresh_token may or may not be included in response. As such, it should only be saved and refreshed when it is included.

Logout

Disconnecting session between app and kakao account in user's app.

Logging in to multiple device is supported. If user login in to multiple devices and log out from one of them, only the device that logged out will be affected(Session disconnected). Logging in to multiple device is supported.

[Request]

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

Request using POST method with user token included in header. For example,

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

[Response]

Response body should be JSON and should include value below.

key description type
id logged out ID signed int64

For example,

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

Linking app

App connection connects logged in user and app with kakao platform which is simillar to user making registration request to your app. In order to use kakao platform correctly app connection must be accomplished first, and it will only be asked initially. If app connection works as it should have, unique ID will be assigned.

Kakao Platform service provide app connection functionality for your convenience. If such setting is activated, procedures for connecting app will be skipped since app connection will be called automatically on initial login.

For setting automatic app connection, go to setting > user management > app connection setting > auto registration in developer site dashboard dev_006.png

If app has called for user information and yet user is not registered while attempting to login, registration window must pop up. You can save specific information about individual users upon signup. This information can be updated after sign up through saving user information.

If you would like to add additional properties of user when registering, you must set such information in properties. Settings for properties must be registered in dashboard of settings > user management > user information through menu. Restrict custom user information column to below 5 in numbers, and restricting each custom user information to below 160 words is recommended. dev_007.png

[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

Request using POST method with user token included in header. If you want to save user information upon linking with the app, you can request for user token and below parameter values with POST. User information can be updated throughsaving user information after registering.

key description required
properties User information of ones being registered. Json type key-value. X

For example, if you wish to request user's age and sex information that they have entered during registration, make a request as below

age and gender should be added at user management setting under custom user information column.

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

[Response]

If app connection request succeed, JSON object will include value below response body.

key description type
id App connected user ID signed int64

For example,

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

Disconnecting App

By unregistering from app, this permanently disconnect app and user registered in kakao platform which is similar to deleting account from app. After un-registration has been completed, recovering account is not possible and can not use kakao platform service any longer. However, user can register with new connection with new data.

When doing unregistering from app, all of user data managed by kakao platform will be deleted. But third party app saved data is not guaranteed to be so by kakao platform service. This must be deleted in third party app(For details, refer to policies and agreement). This is the main difference between deleting account from app and disconnecting account from app.

[Request]

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

Request using POST method with user token included in header. For example,

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

[Response]

If disconnecting App succeed, response body should include JSON object with values below included.

key description type
id user ID which has been disconnected from app signed int64

For example,

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

User information request

This is a functionality for requesting user information, such as user ID and personal details. In order to use such functionality, user token is needed which can be retrieved after successful login.This is also based on the fact that app is connected.

User ID is user's unique ID by app, issued when connecting with app. Using such id, you can identify user in you app. This value will maintain as long as user does not disconnect app from account.

Also, if administrator wants to obtain specific user's information, they can use admin key and user ID to request such.

In order to use such functionality, Admin key is needed to manage all app users. In order to avoid admin key being stolen, please do not make a API call with admin key from app internally but rather from app server.

Additional user information as stated below is provided by using kakao talk and kakaostory service through kakao platform service.

  • nickname: Kakaotalk or kakaostory nickname information
  • profile_image: Kakaotalk or kakaostory profile image URL(size : 480px * 480px ~ 1024px * 1024px)
  • thumbnail_image: Thumbnail profile image URL(size : 110px * 110px, 160px * 213px)

If needed, when connecting with app, specified additional information will be synced with Kakaotalk or KakaoStory service. Even if user has changed user information afterward in Kakaotalk or Kakaostory, such changes won't be affected.

If synchronization with kakaotalk or kakaostory is disabled, additional information will be blanked. Such additional information is interchangeable wtih different data anytime through User information settings. Manual synchronization with user information is also possible using Kakao platform service provided Kakao Talk or 카카오스토리 API. Setting for providing user's additional information by app can be found at Dashboard setting > user management > Setting for connecting app > linking with kakao account menu in developer website.

dev_008.png

[Request]

GET/POST /v1/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 /v1/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 should never be leaked, and since this is sort of a Master key, API call should be made from third party server internally. Admin key can be checked from kakao developer's website. If you used admin key from iOS or Android application's source code, such application will be vulnerable to malicious attacks.

Request using GET/POST with user token/admin key included in header. Parameter below could be included selectively with user token.

key description required
propertyKeys User information key list. Json Array type. X
secure_resource Boolean on whether image url should be https or not. true/false X

For example, if you wish to request entire user information, request should be made as below.

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

For example, if you wish to obtain user information and their age, you should make a request as below.

curl -v -X POST https://kapi.kakao.com/v1/user/me \
  -H "Authorization: Bearer xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d 'propertyKeys=["name","age"]'

If user ID is 12345 and user's name and age should only be obtained, request as below should mae.

curl -v -X POST https://kapi.kakao.com/v1/user/me \
  -H "Authorization: KakaoAK kkkkkkkkkkkkkkkkkkkkkkkkkkkkkk" \
  -d 'target_id_type=user_id&target_id=12345' \
  -d 'propertyKeys=["name","age"]'

[Response]

If user information request has succeeded, response body should include below value in JSON format.

key description type
id user's unique ID signed int64
properties user information. Json type's key-value.
If user's information key has been designated, int will only include information about the key.
String
HTTP/1.1 200 OK
{
    "id":123456789,
    "properties":
    {
        "nickname":"Honggildong",
        "thumbnail_image":"http://xxx.kakao.co.kr/.../aaa.jpg",
        "profile_image":"http://xxx.kakao.co.kr/.../bbb.jpg",
        "custom_field1":"23",
        "custom_field2":"여"
        ...
    }
}
HTTP/1.1 200 OK
{
    "id":123456789,
    "properties":
    {
        "nickname":"홍길동",
        "custom_field1":"23"
        ...
    }
}

Saving user information

Saving user information is a feature to save particular information about user. Beside additional information kakaoplatform service provide, user data can be saved from custom information set in developer site. In order to use such functionality, user token is needed which can be retrieved after successful login. App must be linked prior to this step.

There exists an user information that can not be edited saving user information. For example user ID can not be saved. User's additional information setting by app can be managed through dashboard's setting > user management > user information menu in developer's website. Restrict custom user information column to below 5 in numbers, and restricting each custom user information to below 160 words is recommended. dev_009.png

[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

Request in POST method with user token and below parameter included.

key description required
properties user's information who is requesting to register. Json type's key:value. O

For example, in additional user information, if you wish to update nickname and custom information, age request as below should be made.

age and gender should be added in custom user information column of user management setting.

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

[Response]

Requesting for saving user information should include below values as JSON object when request succeed.

key description type
id user ID signed int64

For example,

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

Requesting user list

Such app's user ID will be received as paging type. Paging is a way to show entire list by requesting with multiple API request. If request is made without no parameter value, 1 ~ 100th user ID list page should show in ascending order . And also, with the result, previous page URL and the next page URL is included. Previous URL should be an URL of page that is previous to the current page. Next page's URL is a URL of page after current page If there are no users to be inputed upon previous or next page, null value should be returned in URL.

As such, if you wish to obtain entire users, follow steps below.

  1. Request without a parameter value.
  2. From the response, deal the user ID and request next page URL.
  3. Repeat step two and when null is returned in URL, stop out of looping steps since it means that there are no users to be received .

If you wish to make special request use from_id, limit, order from below to make ' a list of limited number of app user in order greater/smaller than from_id'.

In order to use such functionality, you need an Admin key to control entire users.In order to avoid admin key from being stolen, API should be called in side the app server itself, not from app internally.

[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

With admin key, below parameter value can be requested.

key description required
limit max number of user included in paging. (minimum of 1, maximum of 100, default 100) Integer types. X
from_id User ID value which is a standard for paging. Generally speaking, Response result is used. If value do not exists, value will be read from smallest ID. Long type X
order Direction of paging being searched. Either in asc / desc order (default to asc) X

For example, if you want to retrieve first 100 users, make request as below.

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

If you wish to obtain USER ID greater than 12345, and would like to get only 3 of them, request as below.

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]

If user information request succeed, values below must be included in response body as JSON.

key description type
elements User ID list. List
total_count Total number of app user. Integer
before_url previous page URL. If previous page does not exist, null. String
after_url Next page URL. if next page does not exist, 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"
}

Validating and getting information from user token

Validates token retrieved by Retrieving user token, or gets additional information about the token.

To refresh tokens by Refresh user token, you will need to check the expire time of a token, periodically.

You can retrieve user tokens using Native SDK, REST API, or Javascript SDK. However you obtained your token, you will be able to use this API.

[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

Request using 'GET' Method, with the token in the request header. NO other parameters are necessary.

Following is an example of the request.

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

[Response]

If the request succeeds, the response body will include the following value in a JSON object.

Key Description Type
id user ID signed int64
expiresInMillis Expire time of the given token(Milli-seconds). 0 또는 양수 signed int64
HTTP/1.1 200 OK
{
    "id":123456789
    "expiresInMillis":239036
}

The above example response will be returned for valid tokens. If the token is invalid, HTTP Status 400 will be returned with error code -2. For expired tokens, Http Status 400 will be returned with error code -401. For more information about the error codes, please refer to Error Codes

The above example response will be returned for valid tokens. If the token is invalid, HTTP Status 400 will be returned with error code -2. For expired tokens, Http Status 401 will be returned with error code -401.

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

For more information about the error codes, please refer to Error Codes.

Dynamic approval

If additional user approval is required when using API, you need a dynamic approval process.

For example, a user who has not approved to send a KakaoTalk message requests Send to me.

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

[Response]

If the request fails, response body will include JSON object as below.

key description
required_scopes approval items required to use the current API
allowed_scopes approval items agreed by the user
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"
  ]
}

You must request dynamic approval, including required_scopes in the API response.

[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
key description required
scope combine the required_scopes received as a response at the API request by ",". O

The dynamic approval process is the same as the Code retrieval process. See the Code retrieval.


Last Modified : 2019-06-11