페이지 이동경로
  • Docs>
  • Kakao Login>
  • REST API

Kakao Login

REST API

This document describes how to integrate Kakao Login APIs into your service with a REST API.

You can test some features described in this document in [Tools] > [REST API Test].

For a Kakao Login button, you can download the resources that Kakao provides or customize it according to your service UI by referring to the Design guide.

Before you begin

REST API is a suitable architectural style to implement Kakao Login both in PC and on the mobile web. To use the Login API, you need to get an authorization code and get tokens with the obtained authorization code. For the detailed login process, refer to Understand concepts > Login.

The Kakao Login using a REST API requires the user authentication process through the user's Kakao Account or Kakao Talk from the client-side and then presents the Consent screen to ask permission. When a user consents, an authorization code is issued.

If a user has already logged in with the Kakao Account, the Login API presents the Consent screen only without asking to log in with Kakao Talk or Kakao Account. On the Kakao Talk in-app browser, users do not have to input their Kakao IDs and passwords.

Login through Kakao Talk on mobile web

You can use the Simple Login function that authenticates a user through Kakao Talk on a mobile web environment so that the user does not need to input the Kakao Account ID and password.

Get authorization code

This is the first step of the Kakao Login process. The Getting authorization code API presents the Consent screen to a user when the user clicks [Login], and then requests an authorization code. The Consent screen is specified in [My Application] > [Kakao Login] > [Consent Items].

The login process flows differently depending on the session of the Kakao Account when requesting an authorization code. If a browser does not retain a session cookie that includes the Kakao Account information, the Consent screen is presented after the user inputs Kakao Account information or logs in with Kakao Talk for authorization. If the session is retained, the Consent screen is presented to the user without any additional process.

When the user consents and clicks [Accept and Continue], the Kakao authorization server issues an authorization code for the user and sends it to the redirect_uri.

Why does not the Consent screen appear?

If a user has already agreed by clicking [Accept and Continue] on Consent screen, the authorization code is issued without the Consent screen displayed. The Consent screen appears the first time when a user links with an app. To display the Consent screen again, unlink from an app and request an authorization code.

If a user clicks [Accept and Continue] on the Consent screen, the Kakao authorization server sends an authorization code as a query string to the redirect_uri in the header field Location with the response code 'HTTP 302 Redirect'. If a user clicks [Cancel], the server adds an error code as a query string to redirect_uri.

The service server must process the request received through redirect_uri, such as getting an authorization code or presenting a specific web page. The obtained authorization code is used to get tokens.

IMPORTANT: How to set or check Redirect URIs

When requesting an authorization code for the first time after integrating the Kakao Login, you may face the "Invalid redirect" error. This error occurs when the redirect_uri in response to requesting an authorization code mismatches with the Redirect URIs that you set on [My Application] > [Kakao Login] > [Redirect URI] page. By referring to Set Redirect URI, you should specify the Redirect URIs in which users proceed Kakao Login process. If you have already set Redirect URIs, check if the URIs you set are exactly the same with the redirect_uri that is returned through the error message.

Request
URL
GET /oauth/authorize?client_id={REST_API_KEY}&redirect_uri={REDIRECT_URI}&response_type=code HTTP/1.1
Host: kauth.kakao.com
Parameter
Name Type Description Required
client_id String REST API key that Kakao issues when you create an app. You can check Your REST API key in [My Application] > [App Keys]. O
redirect_uri String Callback URL that the authorization code is redirected to. O
response_type String Fixed as code. O
state String Random string you create to keep the state between the request and callback.
It is recommended to use this parameter to protect from Cross-Site Request Forgery(CSRF).
X
prompt String Used to request reauthentication by selecting whether to present an interactive UI.
Pass a list of string values delimited by comma(,).

Use either login or none.
login: Used when requesting reauthentication even though a user has already been authenticated by presenting the Kakao Account Login screen to a user. Not available in Kakao Talk in-app browser.
none: Used when requesting an authorization code without presenting a conversational user interface such as the Consent screen to a user. If a user's action is required to get an authorization code, an error is returned.
X
auth_type

To comply with the OAuth 2.0 standard, the 'auth_type' parameter, used to request reauthentication for a user in a logged-in state to enhance security, has been replaced by the 'prompt' parameter. To request reauthentication for a logged-in user, pass "prompt=login" instead of "auth_type=reauthenticate".

Response
Name Type Description Required
code String authorization_code that is used to get an access token. O
state String If this parameter is included in the request, the state parameter value same as the request is passed to the response to protect from CSRF. X
error String Error code that is returned if authentication fails. X
error_description String Error message that is returned if authentication fails. X

Error Message
Error Error_description Description
access_denied User denied access This error is returned if a user clicks [Cancel] on the Consent screen instead of [Accept and Continue]. Implement the subsequent process, such as redirecting the user to the main page.
access_denied Not allowed under age 14 This error is returned if the parental consent for a user under the age of 14 fails. Implement the subsequent process, such as redirecting the user to the main page.
login_required user authentication required. This error is returned if prompt is set to none in the request, and a user authentication has not been completed.
The user needs to log in with the Kakao Account.
consent_required user authentication required. This error is returned if prompt is set to none in the request, and the authorization server requires a user's consent.
The user needs to consent on the Consent screen.
interaction_required need to collect additional personal information. This error is returned if prompt is set to none in the request, but the authorization server requires a user's interaction to proceed.
Implement the subsequent process, such as collecting additional user information or requesting consent to the Terms of Service about Kakao Account.
Sample
Request
https://kauth.kakao.com/oauth/authorize?response_type=code&client_id={REST_API_KEY}&redirect_uri={REDIRECT_URI}
Request: Adding prompt=none
https://kauth.kakao.com/oauth/authorize?response_type=code&client_id={REST_API_KEY}&redirect_uri={REDIRECT_URI}&prompt=none
Response: Success, if user selects [Accept and Continue]
HTTP/1.1 302 Found
Content-Length: 0
Location: {REDIRECT_URI}?code={AUTHORIZE_CODE}
Response: Fail, if user's consent is required (prompt=none is added in request)
HTTP/1.1 302 Found
Content-Length: 0
Location: {REDIRECT_URI}?error=consent_required&error_description=user%20consent%20required.
Response: Fail, if user selects [Cancel]
HTTP/1.1 302 Found
Content-Length: 0
Location: {REDIRECT_URI}?error=access_denied&error_description=User%20denied%20access

Get tokens

The Getting tokens API enables you to get tokens with the obtained authorization code. When you obtain the tokens, the login process is complete. Send a POST request with the required parameters.

In response to the request, tokens (an access token and a refresh token), token type, and validity period are returned in JSON format. Refer to Token information for more detailed information about tokens and its validity period.

Session lifetime after authentication with Kakao Account

After an user logs in with a kakao Account, the login session lasts for 24 hours by default. The session lifetime does not change after the initial authorization. If an user chooses to keep the login status, the authorization session is valid for a month.

The issued access token is used to call the token-based APIs, such as the Retrieving user information API, that requires Kakao Login to get tokens for authorization. You can retrieve token information or refresh the tokens using the refresh token issued with the access token.

Request
URL
POST /oauth/token HTTP/1.1
Host: kauth.kakao.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
Parameter
Name Type Description Required
grant_type String Fixed as authorization_code. O
client_id String REST API key that Kakao issues when you create an app. You can check Your REST API key in [My Application] > [App Keys]. O
redirect_uri String Callback URL that the authorization code is redirected to.
This must coincide with redirect_uri used when requesting an authorization code.
O
code String The obtained authorization code through the Getting authorization code API. O
client_secret String An additional code to strengthen security when issuing tokens.
You can create a client secret code by clicking [Create code] on the [My Application] > [Security] page.
You must add this parameter if 'Client Secret' is activated on this page. Otherwise, the token is not issued from the authorization server.
X
Response
Name Type Description Required
token_type String A type of a token. Fixed as bearer. O
access_token String One of the tokens that authorizes you to call Kakao APIs and identifies users. O
expires_in Integer Validity period in seconds until the access token expires. O
refresh_token String One of the tokens that is used to gain new tokens. O
refresh_token_expires_in Integer Validity period in seconds until the refresh token expires. O
scope String Scopes of user information to be retrieved with the issued access token.
For multiple scopes, each scope is separated by space.
X
Sample
Request
curl -v -X POST "https://kauth.kakao.com/oauth/token" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d "grant_type=authorization_code" \
 -d "client_id={REST_API_KEY}" \
 --data-urlencode "redirect_uri={REDIRECT_URI}" \
 -d "code={AUTHORIZE_CODE}"
Response: Success
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "token_type":"bearer",
    "access_token":"{ACCESS_TOKEN}",
    "expires_in":43199,
    "refresh_token":"{REFRESH_TOKEN}",
    "refresh_token_expires_in":25184000,
    "scope":"account_email profile"
}

Logout

When a user to logs out of service, the Logout API is called, and the access token and the refresh token expire. After the user is logged out, Kakao APIs cannot be called using the user information in the service. If the request is successful, the service user ID is returned.

Even after a user logs out of the service, the Kakao Account session is still retained on the web browser, and the tokens of the app that requests the logout API expire. Implement subsequent actions after users log out such as redirecting them to the main web page of your service.

If you need to have a user log out of the Kakao Account as well as the service on a web browser, you need to expire the Kakao Account session by using an add-on feature, Logout of service and Kakao Account.

Request
Using Access Token
URL
POST /v1/user/logout HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {ACCESS_TOKEN}
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer {ACCESS_TOKEN}
O

Using Admin key
URL
POST /v1/user/logout HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {APP_ADMIN_KEY}
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK {APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
target_id_type String A type of a service user ID.
Fixed as user_id.
O
target_id Long Service user ID to be logged out of the service. O
Response
Name Type Description Required
id Long Service user ID that has been logged out. O
Sample
Request: Using Access Token
curl -v -X POST "https://kapi.kakao.com/v1/user/logout" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
Request: Using Admin key
curl -v -X POST "https://kapi.kakao.com/v1/user/logout" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: KakaoAK {APP_ADMIN_KEY}" \
  -d "target_id_type=user_id" \
  -d "target_id=123456789" 
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":123456789
}

Logout of service and Kakao Account

This feature is an add-on to the Logout API, allowing a user to log out of the service along with the user's Kakao Account session on a web browser expired. Refer to Understand concepts to learn more about this feature and Prerequisites.

The basic Logout functions to limit requesting Kakao APIs with the corresponding user information as the tokens expire. In this case, users need to log out of a service and Kakao Account respectively. On the other hand, with the 'Logout of service and Kakao Account' feature, users can log out of the service right after logging out of Kakao Account by redirecting to the set Logout Redirect URI.

Note that the request URL and parameters are different depending on logout types because the logout process flows differently. Set client_id to the app's REST API key and Logout Redirect URI to the service server address where logging out of the service will be proceeded as query parameters, and send a GET request. If you want to keep some value during the logout process, put it in state parameter.

You need to implement the subsequent process internally according to the logout result passed to Logout Redirect URI. The Kakao authorization server does not get the result of the logout process from the service.

Request
URL
GET /oauth/logout?client_id={REST_API_KEY}&logout_redirect_uri={LOGOUT_REDIRECT_URI} HTTP/1.1
Host: kauth.kakao.com
Parameter
Name Type Description Required
client_id String REST API key that Kakao issues when you create an app. You can check Your REST API key in [My Application] > [App Keys]. O
logout_redirect_uri String Logout Redirect URI where logging out of the service will be proceeded.
One of the URIs set on the [My Application] > [Kakao Login] > [Logout Redirect URI] page .
O
state String Random string you create to keep the state between the request and callback. X
Response
Name Type Description Required
state String If this parameter is included in the request, the state parameter value same as the request is passed to the response to protect from CSRF. X
Sample
Request
curl -v -X GET "https://kauth.kakao.com/oauth/logout?client_id={YOUR_REST_API_KEY}&logout_redirect_uri={YOUR_LOGOUT_REDIRECT_URI}"
Response
HTTP/1.1 302 Found
Location: {LOGOUT_REDIRECT_URI}?state={STATE}

Unlink

When using a REST API, you can request the Unlink API in two ways — with an access token or an Admin key. We provide an alternative way just in case you cannot request the Unlink API with an access token such as if the service is terminated.

Include the access token in the request header, and send a POST request. If you request the Unlink API using an Admin key, you must specify a user to be logged out in the request.

When the Unlink API request succeeds, the user is also logged out and the access and refresh tokens expire. If the request is successful, the service user ID is returned.

CAUTION

Keep your app's Admin key safe not to be revealed. You should make REST API requests with an Admin key only in the server, NOT in your source code.

Request
Using Access Token
URL
POST /v1/user/unlink HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {ACCESS_TOKEN}
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer {ACCESS_TOKEN}
O

Using Admin key
URL
POST /v1/user/unlink HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {APP_ADMIN_KEY}
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK {APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
target_id_type String A type of a service user ID.
Fixed as user_id.
O
target_id Long Service user ID to be unlinked from the service. O
Response
Name Type Description Required
id Long Service user ID that has been successfully unlinked from the service. O
Sample
Request: Using Access Token
curl -v -X POST "https://kapi.kakao.com/v1/user/unlink" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
Request: Using Admin Key
curl -v -X POST "https://kapi.kakao.com/v1/user/unlink" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: KakaoAK {APP_ADMIN_KEY}" \
  -d "target_id_type=user_id" \
  -d "target_id=123456789" 
Response
{
  "id": 123456789
}

Retrieve token information

The Retrieving token information API retrieves the validity period of the access and refresh tokens in seconds, app ID and service user ID. Include the access token in the request header, and send a GET request.

If the request is successful, the detailed information about the token is returned in JSON format. If an error occurs, see below or Reference Information > REST API > Response code.

Code Description HTTP Status
-1 Internal error occurs temporarily on the Kakao platform service.
It is recommended to handle this temporary error with a error message without making tokens expire or log out.
400
-2 If the required parameter is not included in the request or its data type has something wrong or out of range.
If the given token information has something wrong with the format, check if you use the precise access token when requesting.
400
-401 If you request API using the expired token or invalid app key.
If you use the wrong or invalid token value, you need to refresh the access token.
401

For other errors besides these cases above, it is recommended to log a user out because the status of an app, the user, or tokens may not be valid.

Request
URL
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
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer {ACCESS_TOKEN}
O
Response
Name Type Description Required
id Long Service user ID. O
expires_in Integer Validity period in seconds until the access token expires. O
app_id Integer App ID that an access token has been issued for. O
appId, expiresInMillis

To maintain consistency in parameter names and units in a REST API and the Kakao SDK, we changed 'appId' to 'app_id' and 'expiresInMillis' to 'expires_in'.

Sample
Request
curl -v -X GET "https://kapi.kakao.com/v1/user/access_token_info" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
Response
HTTP/1.1 200 OK
{
    "id":123456789,
    "expires_in": 7199,
    "app_id":1234
}

Refresh tokens

The Refreshing tokens API refreshes the access and refresh tokens.

Include the refresh token and required parameters, and send a POST request. The response is returned in JSON format. The refresh_token is returned only when the validity period of the refresh token is left less than a month, which means that you may not get refresh_token and refresh_token_expires_in in your response.

When you use the SDK for JavaScript, you also need to refresh an access token via REST API due to security policy.

Request
URL
POST /oauth/token HTTP/1.1
Host: kauth.kakao.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
Parameter
Name Type Description Required
grant_type String Fixed as refresh_token. O
client_id String REST API key that Kakao issues when you create an app. You can check Your REST API key in [My Application] > [App Keys]. O
refresh_token String One of the tokens that is used to gain new tokens that have been issued in response to the Getting tokens API. O
client_secret String An additional code to strengthen security when issuing tokens.
You can create a client secret code by clicking [Create code] on the [My Application] > [Security] page.
You must add this parameter if 'Client Secret' is activated on this page. Otherwise, the token is not issued from the authorization server.
X
Response
Name Type Description Required
token_type String A type of a token, fixed as bearer. O
access_token String A new access token that has been refreshed. O
expires_in Integer Validity period in seconds until the access token expires. O
refresh_token String A new refresh token that has been refreshed.
Possible to refresh only when the validity period is left less than a month.
X
refresh_token_expires_in Integer Validity period in seconds until the refresh token expires. X
Sample
Request
curl -v -X POST "https://kauth.kakao.com/oauth/token" \
 -H "Content-Type: application/x-www-form-urlencoded" \
 -d "grant_type=refresh_token" \
 -d "client_id={REST_API_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
    "refresh_token_expires_in":25184000,  //optional
    "expires_in":43199,
}

Retrieve user information

This API enables you to retrieve Kakao Account information of a user who is logged into Kakao. You can request this API with either an access token or an Admin key. You must be careful not to leak your Admin key that has all authorities and use it only when requesting from the server.

IMPORTANT

To retrieve user data, you must set consent items and obtain user's consent for the data that your service needs. If a user does not consent, you cannot get the user data. To check which scopes a user has already agreed, you can call the Retrieving consent details API and check the agreed scopes first.

Send a GET or POST request by including either the access token or the Admin key in the request header. If you use the Admin key, you should also pass a service user ID. You can also specify the scopes of user information to be retrieved using property_keys or decide whether to use HTTPS.

Moreover, you can store the user information that is used in your service such as a nickname into the Kakao Account with the User Properties feature.

If the request is successful, the user information is returned in JSON format.

Request
Using Access Token
URL
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
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer {ACCESS_TOKEN}
O

Parameter

Name Type Description Required
secure_resource Boolean Whether to use HTTPS for the image URL scheme.
If true, HTTPS is used. (Default: false)
X
property_keys String[] Property key list in ["properties.nickname"] format. X

Using Admin key
URL
GET/POST /v2/user/me HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {APP_ADMIN_KEY}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK {APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
target_id_type String A type of a service user ID.
Fixed as user_id.
O
target_id Long Service user ID. O
secure_resource Boolean Whether to use HTTPS for the image URL scheme.
If true, HTTPS is used. (Default: false)
X
property_keys String[] Property key list in ["properties.nickname"] format. X

property_keys

Name Description
properties.nickname User's nickname used in a service.
(Default: Kakao Account's nickname that is set when linked with your app)
properties.profile_image User's profile image URL used in a service.
(Default: image URL with a size of 640*640 that is set as Kakao Account's profile at the point when the user is linked with an app.)
properties.thumbnail_image User's profile thumbnail image URL used in a service.
(Default: thumbnail image URL with a size of 110x110 pixels that is set as Kakao Account's profile thumbnail image at the point when the user is linked with an app.)
kakao_account.profile Whether to own Kakao Account's profile,
Nickname and profile URL that are reflected in real time.
kakao_account.email Whether to own Kakao Account's email,
email, verification status and validation status of email.
kakao_account.age_range Whether to own Kakao Account's age range, age range.
kakao_account.birthday Whether to own Kakao Account's birthday, birthday.
kakao_account.gender Whether to own Kakao Account's gender, gender.
Response
Name Type Description Required
id Long Service user ID. O
has_signed_up Boolean Only returned when the Auto-link setting is disabled.
Whether the user is completely linked with (signed up) your app.
false: Preregistered
true: Registered
X
connected_at Datetime The time when the user is linked with a service in UTC*. X
synched_at Datetime The time when the user is logged in through Kakao Sync Simple Signup in UTC*.
This value is only passed for Kakao Sync service users. In this case, its value is the same as connected_at.
X
properties JSON Additional user information saved on the Kakao platform to use it later.
Refer to Prerequisites > User properties.
X
kakao_account JSON Kakao Account information. X

* The time is based on Coordinated Universal Time(UTC), being 9 hours behind Korean Standard Time(KST). For the format of time, refer to RFC3339: Date and Time on the Internet.

kakao_account
Name Type Description Required
profile_needs_agreement Boolean Whether consent to profile is required.

Required user consent: Profile Info(nickname/profile image)
X
profile_nickname_needs_agreement Boolean Whether consent to nickname is required.

Required user consent: Nickname
X
profile_image_needs_agreement Boolean Whether consent to profile image is required.

Required user consent: Profile image
X
profile JSON Profile information

Required user consent: Profile Info(nickname/profile image), Nickname, Profile image
X
email_needs_agreement Boolean Whether consent to email is required.

Required user consent: Email
X
is_email_valid Boolean If the email has expired because it is used for another Kakao Account, false is returned.

Required user consent: Email
X
is_email_verified Boolean Verification status of email

Required user consent: Email.
X
email String Representative email

Required user consent: Email
X
name_needs_agreement Boolean Whether consent to name is required.

Required consent item: Name
X
name String Name of Kakao Account.

Required consent item: Name
X
age_range_needs_agreement Boolean Whether consent to age range is required.

Required user consent: Age range
X
age_range String Age range.
1~9, 10~14, 15~19, 20~29, 30~39, 40~49, 50~59, 60~69, 70~79, 80~89, 90~

Required user consent: Age range
X
birthyear_needs_agreement Boolean Whether consent to birthyear is required.

Required user consent: Birth Year
X
birthyear String Birthyear in YYYY format.

Required user consent: Birth Year
X
birthday_needs_agreement Boolean Whether consent to birthday is required.

Required user consent: Birthday
X
birthday String Birthday in MMDD format.

Required user consent: Birthday
X
birthday_type String Solar or Lunar birthday.
SOLAR or LUNAR.

Required user consent: Birthday
X
gender_needs_agreement Boolean Whether consent to gender is required.

Required user consent: Gender
X
gender String Gender.
female or male.

Required user consent: Gender
X
phone_number_needs_agreement Boolean Whether consent to phone number is required.

Required user consent: Phone number
X
phone_number String Phone number. For domestic numbers, in +82 00 0000 0000 format.
For international numbers, the position of a hyphen(-) or a seperator may differ according to countries.
Refer to libphonenumber.

Required user consent: Phone number
X
ci_needs_agreement Boolean Whether consent to CI for a reference is required.

Required user consent: CI(Connecting Information)
X
ci String An encoded identifier to check if the same user has already been registered (Connecting Information).

Required user consent: CI(Connecting Information)
X
ci_authenticated_at Datetime The time when Cerificate Authority issues CI in UTC*.

Required user consent: CI(Connecting Information)
X

* The time is based on Coordinated Universal Time(UTC), being 9 hours behind Korean Standard Time(KST). For the format of time, refer to RFC3339: Date and Time on the Internet.

IMPORTANT: Providing separated scopes for profile information

From June 25, 2021, we provide the profile information separated as 'Nickname' and 'Profile image'. You can request consent to desired profile information by setting desired scopes respectively. If you create a new app, the separated scopes for profile information are applied to the app. If you have enabled the 'Profile Info(nickname/profile image)' scope, you can continue to use that scope. In this case, you do not need to change the app settings, and there is no change in API response. But if you want to use the new scpes in the existing app, fill out the request form. In this case, the API response may change. Refer to Notice for more details.

profile
Name Type Description Required
nickname String Nickname.

Required user consent: Profile Info(nickname/profile image) or Nickname
X
thumbnail_image_url String Profile thumbnail image URL.
110x110 pixels or 100x100 pixels.

Required user consent: Profile Info(nickname/profile image) or Profile image
X
profile_image_url String Profile image URL.
640x640 pixels or 480x480 pixels.

Required user consent: Profile Info(nickname/profile image) or Profile image
X
is_default_image Boolean Whether the default image is used for profile image.
true: the default profile image is used since a user has not registered any profile image.
false: the user's profile image is used.

Required user consent: Profile Info(nickname/profile image) or Profile image
NOTE: From Tuesday, June 1, 2021, if is_default_image is true, the URL of the default profile image is returned as profile_image_url and thumbnail_image_url. Refer to DevTalk for more details.
X
Sample
Request: All information using Access Token
curl -v -X GET "https://kapi.kakao.com/v2/user/me" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
Request: Email using Access Token
curl -v -X POST "https://kapi.kakao.com/v2/user/me" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  --data-urlencode 'property_keys=["kakao_account.email"]'
Request: Email using Admin Key
curl -v -X POST "https://kapi.kakao.com/v2/user/me" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: KakaoAK {APP_ADMIN_KEY}" \
  -d "target_id_type=user_id" \
  -d "target_id=123456789" \
  --data-urlencode 'property_keys=["kakao_account.email"]'
Response: Success
HTTP/1.1 200 OK
{
    "id":123456789,
    "connected_at": "2021-09-23T06:08:31Z",
    "kakao_account": { 
        "profile_needs_agreement": false,
        "profile": {
            "nickname": "Mike",
            "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
        },
        "email_needs_agreement":false, 
        "is_email_valid": true,   
        "is_email_verified": true,   
        "email": "sample@sample.com",
        "name_needs_agreement": false,
        "name": "Cool Mike",
        "age_range_needs_agreement":false,
        "age_range":"20~29",
        "birthday_needs_agreement":false,
        "birthday":"1130",
        "gender_needs_agreement":false,
        "gender":"male"
    },
    "properties":{
        "nickname":"MikeKakaoTalk",
        "thumbnail_image":"http://xxx.kakao.co.kr/.../aaa.jpg",
        "profile_image":"http://xxx.kakao.co.kr/.../bbb.jpg",
        "custom_field1":"23",
        "custom_field2":"MALE",
        ...
    }
}
Response: Success, if user consents to 'Nickname' only
HTTP/1.1 200 OK
{
    "id":123456789,
    "kakao_account": { 
        "profile__nickname_needs_agreement": false,
        "profile": {
            "nickname": "Mike"
        },
    },
    "properties":{
        "nickname":"MikeKakaoTalk",
        "custom_field1":"23",
        "custom_field2":"MALE",
        ...
    }
}

Store user information

This API stores or update additional user information on the Kakao platform to use in a service, which is called 'User properties'. You must use the property keys designated in [My Application] > [Kakao Login] > [User Properties].

Send a POST request by passing the access token in the request header and properties as data-urlencode parameter. For example, if you want to store or update nickname and age in your app, you can request as the following code snippet. If the request is successful, the user ID requested to store information is returned in your response.

After storing user information under the designated property keys, you can retrieve all or some of the saved user information by Retrieving user information.

Request
URL
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
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer {ACCESS_TOKEN}
O
Parameter
Name Type Description Required
properties JSON A list of user information to be stored in {"key":"value"} format. O
Response
Name Type Description Required
id Long Service user ID. O
Sample
Request to save nickname and age
curl -v -X POST "https://kapi.kakao.com/v1/user/update_profile" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  --data-urlencode 'properties={"nickname":"Mike","age":"22"}'
Response
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":123456789
}

Retrieve user list

This API is for an app administrator to retrieve a list of information on app users.

Send a GET request by passing your Admin key in the header. You can designate the order and range of service user IDs to be retrieved using the request parameters. The list of service user IDs is returned in JSON format as you request. If all service user IDs are not displayed on a single page, the response includes the URLs for the previous and next page.

CAUTION

You must keep your Admin key safe not to be revealed. Thus, when you use the Admin key, call the Retrieving user information API only from a server.

Request
URL
GET /v1/user/ids HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {APP_ADMIN_KEY}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK {APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
limit Integer Number of users per a page.
(Default: 100, Minimum: 1, Maximum: 100)
X
from_id Long The service user ID starting the page from.
The user list includes from_id and higher service user IDs.
Use one of the service user IDs in the response for this parameter.
If not specified, the user ID with the lowest number comes first.
X
order String Page search direction.

Use either asc or desc.
asc: sort in ascending order.
desc: sort in descending order.
(Default: asc)
X
Response
Name Type Description Required
elements Integer[] List of service user IDs. O
total_count Integer Total number of app users.
Deprecated: No longer available after January 10, 2022.
O
before_url String Previous page URL.
If there is no previous page, null is returned.
X
after_url String Next page URL.
If there is no next page, null is returned.
X
total_count

'total_count', the response field of the Retrieving user list API, will be deprecated on January 10, 2022. To check the number of app users, go to [My Application] > [Statistics] > [Users] and see the user activity information. For more information, refer to DevTalk Notice.

Sample
Request: 100 users from the beginning
curl -v -X GET "https://kapi.kakao.com/v1/user/ids" \
  -H "Authorization: KakaoAK {APP_ADMIN_KEY}"
Request: 3 users with ID numbers 12345 or higher
curl -v -G GET "https://kapi.kakao.com/v1/user/ids" \
  -H "Authorization: KakaoAK {APP_ADMIN_KEY}" \
  -d 'limit=3&order=asc' \
  -d 'from_id=12345'
Response
HTTP/1.1 200 OK
{
    "elements": [
        1376016924426111111, 1376016924426222222, 1376016924426333333
    ], 
    "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"
}

Retrieve multiple user information

This API is for an app administrator to retrieve the information of multiple app users. You must be careful not to leak your Admin key that has all authorities and use it only when requesting from the server.

Include the app's Admin key in the request header, and send a GET request. Pass the list of users to be retrieved through the target_ids parameter as an array type.

If the request is successful, the list of the requested user information is returned. The user's Service user ID and connected time are included in the response by default.

You can also request additional user information using the property_keys parameter. For this, you must set consent item to retrieve the user information.

Pass the user information to be retrieved and the predefined keys as the value of property_keys with a string array type.

property_keys=["id","has_signed_up","properties.nickname","kakao_account.has_email"]

For the user information with sub-scopes, you can add a dot(.) to the key as the value of property_keys. Then, you can request all sub-scopes under the key.

property_keys=["kakao_account.","properties."]

If you want to request some sub-scopes only, specify the sub-scope's key after the dot (.) and pass it.

property_keys=["kakao_account.email","kakao_account.gender"]

For the inclusive scopes in which related information is included, you can retrieve the related information along with the scope when you request. For example, if you request email information by specifying "kakao_account.email" as the value of property_keys, the related information — kakao_account.has_email, kakao_account.email_needs_agreement, kakao_account.is_email_valid, and kakao_account.is_email_verified — are returned along with kakao_account.email.

To request all user information, pass the following values for property_keys.

property_keys=["kakao_account.","properties.","has_signed_up"]

To request all user information of a specific user without specifying any parameters, use the Retrieve user information API.

Request
URL
GET /v2/app/users HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {APP_ADMIN_KEY}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK {APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
target_ids Long[] List of user IDs to be retrieved.
You can request information of at most 100 users.
If you request user information by specifying property_keys, you can request information of up to 20 users.
O
target_id_type String Type of user ID set as target_ids.
Fixed as user_id.
O
property_keys String[] Property key for user information to be retrieved.
You can use the keys of User information and User property.
If not specified, default information is returned only in response.
X
Response
Name Type Description Required
elements List<users_info> List of user information.
By default, only basic user information such as ID is included in the response of Retrieving multiple user information API .
You can request to retrieve more user information using the property_keys parameter.
To see more available user information, refer to User information.
O
users_info
Name Type Description
id Long Service user ID (user_id).
synched_at Datetime The time when the user is logged in through Kakao Sync Simple Signup in UTC*.
connected_at Datetime The time when the user is linked with a service in UTC*.
kakao_account JSON Kakao Account information.
properties JSON Additional user information saved on the Kakao platform to use it later.
Refer to User properties.

*The time is based on Coordinated Universal Time(UTC), being 9 hours behind Korean Standard Time(KST). For the format of time, refer to RFC3339: Date and Time on the Internet.

Sample
Request
curl -v -G GET "https://kapi.kakao.com/v2/app/users" \
    -H "Authorization: KakaoAK {APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    --data-urlencode "target_ids=[1399634384,1406264199]" 
Request: Email and profile by specifying property_keys
curl -v -G GET "https://kapi.kakao.com/v2/app/users" \
    -H "Authorization: KakaoAK {APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    --data-urlencode "target_ids=[1399634384,1406264199]" \
    --data-urlencode 'property_keys=["kakao_account.email","kakao_account.profile"]'
Request: All available user information
curl -v -G GET "https://kapi.kakao.com/v2/app/users" \
    -H "Authorization: KakaoAK {SERVICE_APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    --data-urlencode "target_ids=[1285016924429472463]" \
    --data-urlencode 'property_keys=["kakao_account.","properties.","has_signed_up"]'
Response
[
    {
        "id":1406264199,
        "connected_at":"2020-07-14T06:15:36Z",
        // Only returned for the service that applies Kakao Sync. 
        "synched_at":"2020-07-14T06:15:36Z"
    },
    {
        "id":1399634384,
        "connected_at":"2020-07-06T09:55:51Z",
        // Only returned for the service that applies Kakao Sync. 
        "synched_at":"2020-07-06T09:55:51Z"
    }
    ...
]
Response: Email and profile
[
    {
        "id":1399634384,
        "connected_at":"2020-07-06T09:55:51Z",
        "kakao_account":{
            "profile_needs_agreement":false,
            "profile":{
                "nickname":"춘식이",
                "thumbnail_image_url":"http://k.kakaocdn.net/dn/zK7QA/btqzpE4aqO1/pl2HpfVBUI9s1SSrstperq/img_110x110.jpg",
                "profile_image_url":"http://k.kakaocdn.net/dn/zK7QA/btqzpE4aqO1/pl2HpfVBUI9s1wqsgrEAVk/img_640x640.jpg",
                "is_default_image":false
            },
            "has_email":true,
            "email_needs_agreement":false,
            "is_email_valid":true,
            "is_email_verified":true,
            "email":"sweetpotato@kakao.com"
        }
    },
    {
        "id":1406264199,
        "connected_at":"2020-07-14T06:15:36Z",
        "kakao_account":{
            "profile_needs_agreement":false,
            "profile":{
                "nickname":"나비",
                "thumbnail_image_url":"http://k.kakaocdn.net/dn/DCjQu/btqti3A2gEc/zgQwddmSnG7CDfmKtTO1/img_110x110.jpg",
                "profile_image_url":"http://k.kakaocdn.net/dn/DCjQu/btqti3A2gEc/zgip1O4JmSnG8sDfmKtTO1/img_640x640.jpg",
                "is_default_image":false
            },
            "has_email":true,
            "email_needs_agreement":true
            }
    }
    ...
]
Response: All available user information

Retrieve consent details

This API enables you to retrieve the detailed information of the scopes (consent items) that a user has agreed to. You can check all scopes set in [My Application] > [Kakao Login] > [Consent Items], check if a user has agreed to each scope and if the scope is revocable. If a user has agreed to a scope before, the scope is included in the response even though your app is currently not using the scope.

For authorization, you can use an access token or your Admin key. Send a GET request with the issued access token or your Admin key in the request header. When requesting with the Admin key, you must pass the service user ID (user_id) of the target user that you want to retrieve.

If the request is successful, the API returns a JSON array of the scopes set in the app. If the user has agreed to a scope, the value of agreed is returned to true.

You can also designate the scopes to check the details by specifying the scopes parameter. If the request is successful, the response includes only the detailed information of the specified scopes.

Request

Using Access Token

URL
GET /v2/user/scopes HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {ACCESS_TOKEN}
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer {ACCESS_TOKEN}
O
Parameter
Name Type Description Required
scopes String[] Used when you retrieve specific scopes only.
List of scope IDs you want to retrieve.
You can pass multiple scopes by separating by comma(,).
X

Using Admin key

URL
GET /v2/user/scopes HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {APP_ADMIN_KEY}
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK {APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
target_id_type String A type of a service user ID.
Fixed as user_id.
O
target_id Long Service user ID of the user to be retrieved. O
scopes String[] Used when you retrieve specific scopes only.
List of scope IDs you want to retrieve.
You can pass multiple scopes by separating by comma(,).
X
Response
Name Type Description Required
id Long Service user ID. O
scopes scopes[] List of scope IDs. O
scopes
Name Type Description Required
id String Scope ID. O
display_name String Name or description of the scope (consent item) displayed on the Consent screen. O
type String Scope type. PRIVACY or SERVICE.
PRIVACY: scopes for Personal Information
SERVICE: scopes for Permission
O
using Boolean Whether your app is using the scope.
true: Using the scope.
false: Not using the scope even though the user has agreed to.
O
agreed Boolean Whether the user has agreed to the scope.
true: The user has agreed.
false: The user has not agreed.
O
revocable Boolean Whether you can revoke this scope.
Only returned if the user has agreed to the scope.("agreed"=true)
true: Possible to revoke the scope.
false: Impossible to revoke the scope.
X
Sample
Request: Using Access Token
curl -v -X GET "https://kapi.kakao.com/v2/user/scopes" \
    -H "Authorization: Bearer {ACCESS_TOKEN}"
Request: Retrieving specific scopes only using Access Token
curl -v -G GET "https://kapi.kakao.com/v2/user/scopes" \
    -H "Authorization: Bearer {ACCESS_TOKEN}" \
    --data-urlencode 'scopes=["account_email","friends"]'
Request: Using Admin key
curl -v -G GET "https://kapi.kakao.com/v2/user/scopes" \
    -H "Authorization: KakaoAK {APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    -d "target_id=123456789" 
Response: Success
{
    "id":123456789,
    "scopes":[
        {
            "id":"profile",
            "display_name":"Profile Info(nickname/profile image)",
            "type":"PRIVACY",
            "using":true,           // Whether your app is using this scope or not
            "agreed":true,          // Whether the user has agreed to this scope or not
            "revocable":false       // Whether you can revoke this scope or not
        },
        {
            "id":"account_email",
            "display_name":"Email",
            "type":"PRIVACY",
            "using":true,           // Whether your app is using this scope or not
            "agreed":true,          // Whether the user has agreed to this scope or not
            "revocable":true        // Whether you can revoke this scope or not
        },
        {
            "id":"shipping_address",
            "display_name":"Shipping information (receiver, shipping address, phone number)",
            "type":"PRIVACY",
            "using":true,           // Whether your app is using this scope or not
            "agreed":false         // Whether the user has agreed to this scope or not
        },
        ...
    ]
}
Response: Consent details of Email and Friends List in Kakao Service
{
    "id":123456789,
    "scopes":
    [
        {
            "id":"friends",
            "display_name":"Friends List in Kakao Service(Including profile image, nickname, and favorites)",
            "type":"PRIVACY",
            "using":true,
            "agreed":true,
            "revocable":false
        },
        {
            "id":"account_email",
            "display_name":"Email",
            "type":"PRIVACY",
            "using":true,
            "agreed":false
        }
    ]
}

Revoke consent

This API revokes the scope that a user has agreed to. You can only revoke the scope with "revocable":true among the scopes retrieved through the Retrieving consent details API.

For authorization, you can use an access token or your Admin key. Include the issued access token or your Admin key in the request header, and send a POST request with the list of scopes that you want to revoke. When requesting with the Admin key, you must pass the service user ID (user_id) of the target user.

If the request is successful, the API returns a list of the consent items (scopes) that the changes are applied. The response includes the information about if your app is using the scope, if the user has agreed to the scope, or if the scope is revocable. If the requested scope is successfully revoked, the value of agreed is returned to false.

Request

Using Access Token

URL
POST /v2/user/revoke/scopes HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer {ACCESS_TOKEN}
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer {ACCESS_TOKEN}
O
Parameter
Name Type Description Required
scopes String[] List of scope IDs you want to revoke.
You can revoke only the scope with "revocable":true among the scopes retrieved through the Retrieving consent details API.
O

Using Admin key

URL
POST /v2/user/revoke/scopes HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK {APP_ADMIN_KEY}
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK {APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
target_id_type String A type of a service user ID.
Fixed as user_id.
O
target_id Long Service user ID of a taget user. O
scopes String[] List of scope IDs you want to revoke.
You can revoke only the scope with "revocable":true among the scopes retrieved through the Retrieving consent details API.
O
Response
Sample
Request: Using Access Token
curl -v -X POST "https://kapi.kakao.com/v2/user/revoke/scopes" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Authorization: Bearer {ACCESS_TOKEN}" \
    --data-urlencode 'scopes=["account_email"]'
Request: Using Admin key
curl -v -X POST "https://kapi.kakao.com/v2/user/revoke/scopes" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Authorization: KakaoAK {APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    -d "target_id=123456789" \
    --data-urlencode 'scopes=["account_email"]'
Response: Success, if consent to Email is rovoked
{
    "id":123456789,
    "scopes":[
        {
            "id":"profile",
            "display_name":"Profile Info(nickname/profile image)",
            "type":"PRIVACY",
            "using":true,
            "agreed":true,
            "revocable":false
        },
        {
            "id":"friends",
            "display_name":"Friends List in Kakao Service(Including profile image, nickname, and favorites)",
            "type":"PRIVACY",
            "using":true,
            "agreed":true,
            "revocable":false
        },
        {
            "id":"account_email",
            "display_name":"Email",
            "type":"PRIVACY",
            "using":true,
            "agreed":false          //Changed to 'false' if the consent is successfully revoked
        },
        {
            "id":"talk_chats",
            "display_name":"Read chat lists in KakaoTalk",
            "type":"SERVICE",
            "using":true,
            "agreed":true,
            "revocable":false
        },
        ...
    ]
}
Response: Fail, if requesting to revoke 'Required consent item'
HTTP/1.1 403 Forbidden
{
    "msg":"[profile] is not revocable. check out if it's set as required on developers.kakao.com",
    "code":-3
}
Response: Fail, if the requested scope ID is wrong
HTTP/1.1 400 Bad Request
{
  "msg":"There is no scopes to revoke. check out if given scope id([email]) is correct again.",
  "code":-2
}

Request additional consent

IMPORTANT: Set consent items

To use this API, you must configure consent items for the required scopes.

This API prompts the Consent screen to request additional permission or specific personal information for the service if the user has not agreed once logging in with Kakao. Before using this API, read Understand concepts > Request additional consent thoroughly for a better understanding.

You can use this API, as an example, for a user who has not agreed to provide a birthday once logging in to the service. When the service needs birthday information to provide a service in the middle of the use of the service, request the information through this API.

To request this API, add the scopes you want to request consent in the scope parameter to the request of the Getting authorization code API.

Calling this API presents the Consent screen that includes the requested scope as a consent item. When a user selects [Accept and Continue] on the Consent screen, the request is successfully completed. If the user selects [Cancel], the request is failed.

If the request is successful, you will get a new authorization code when a user consents to the scope. Then, request the Getting tokens API to get new tokens using the newly issued authorization code. After that, you must use the new tokens when you request the Kakao APIs.

Request
URL
GET /oauth/authorize?client_id={REST_API_KEY}&redirect_uri={REDIRECT_URI}&response_type=code&scope={required_scopes.join(',')} HTTP/1.1
Host: kauth.kakao.com
Parameter
Name Type Description Required
client_id String REST API key that Kakao issues when you create an app. You can check Your REST API key in [My Application] > [App Keys]. O
redirect_uri String URI to get the authorization code. O
response_type String Fixed as code. O
scope String Scopes of user information you want to request additional consent.
You can pass multiple scopes by separating by comma(,).
Refer to User information.
O
state String Random string you create to keep the state between the request and callback.
It is recommended to use this parameter to protect from Cross-Site Request Forgery(CSRF).
X
Response
Sample
Request: Additional consent to Email
https://kauth.kakao.com/oauth/authorize?client_id={REST_API_KEY}&redirect_uri={REDIRECT_URI}&response_type=code&scope=account_email

Advanced: Manual signup

IMPORTANT

The Manual signup API is only for the app that the Auto-link option is disabled. To check whether to use this feature, go to [My Application] > [Kakao Login] and see if the 'Auto-link with an app when logging in' option is displayed. If not displayed, your app is using the Auto-link feature. If displayed, you can choose whether to automatically link a user with your app when the user logs in. If this option is set to 'Disabled', you must use the Manual signup API to link the user.

The Manual signup API manually links a user with your app to complete signup when the Auto-link is disabled. The Auto-link feature allows you to link a user with your app automatically, which is set by default. To manually link users with your app, you need a separate negotiation with Kakao.

Here are some cases that you must link users with your app manually:

  • If a signup is not completed after a user consents to the use of service when logging in.
    • If a user is signed up through a separate verification process or by inputting additional information after logging in.
    • If a user is not signed up immediately until the service approves the signup request.
  • If a service needs to manage users' linked status internally.

The service with the Auto-link option disabled must call the Manual signup API to link the service app with a user. You must check if users' signed-up status coincides with the linked status, and then complete signup by calling the Manual signup API. Thus, we highly recommend enabling the Auto-link option except for inevitable cases.

Unlink for users who have not completed a signup

If a user is not linked using the Manual signup API in the preregister state within 24 hours, the user is considered as not signed up and turned to be in an unlink state. If you register unlink callback, you will get an unlink callback when a user unlinks from your app. In this case, you must call the unlink API for the user and delete the user information. For more details, refer to Notice.

Send a POST request by including the access token in the request header. When you request the Manual signup API, you can also request to store user properties. Even after the link, you can also store user properties through the Storing user information API. When a user is unlinked, the user properties are deleted.

User information to be provided according to user's linked status

If a user is in a preregistered status, which means the user has not completely signed up through the Manual signup API, only some of the following user information are provided through the Retrieve user information and Retrieve multiple user information

Name Key
Service User ID id
User's unique ID uuid
Profile information (Nickname, Profile image) kakao_account.profile
Checking if the user is linked has_signed_up
Time when the user is linked connected_at
Kakao Account (email) kakao_account.email
Checking if email is valid is_email_valid
Checking if email is verified is_email_verified
Request
URL
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
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer {ACCESS_TOKEN}
O
Parameter
Name Type Description Required
properties JSON A list of user information in {"key":"value"} format.
Used when you want to store user properties when linking a user.
Refer to User properties and Store user information.
X
Response
Name Type Description Required
id Long Service user ID that is linked to your app. O
Sample
Request: Link without storing user properties
curl -v -X POST "https://kapi.kakao.com/v1/user/signup" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
Request: Link and store nickname in property
curl -v -X POST "https://kapi.kakao.com/v1/user/signup" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  --data-urlencode 'properties={"nickname":"Ryan"}'
Response: Success
HTTP/1.1 200 OK
{
    "id":1376016924429759228
}
Response: Fail, if user is already linked with app
HTTP/1.1 400 Bad Request
{
    "msg":"already registered",
    "code":-102
}
Response: Fail, if invalid access tokent is used in request
HTTP/1.1 401 Unauthorized
{
    "msg":"this access token does not exist",
    "code":-401
}
Response: Fail, if unregistered property key is used in request
HTTP/1.1 400 Bad Request
{
    "msg":"user property not found ([gender, age] for appId={APP_ID})",
    "code":-201
}

See more