kakao developers

Prerequisites

This document explains what you have to do before integrating Kakao Login.

Tag used in this document

Tag	Description
Required	You must apply the settings marked with this tag before integrating Kakao Login into your service.
Optional	You can optionally apply the settings marked with this tag depending on the functions you want to use.

To integrate Kakao Login into your service, you MUST:

1. Activate Kakao Login.
2. Register Redirect URI.
3. Set consent items.

You can additionally adopt other functions with the Optional tag attached.

Activate Kakao Login Required

Kakao Login is an essential function to leverage user-based services such as Kakao Sync, Kakao Talk, or Kakao Story. Refer to Kakao Login to learn more about Kakao Login.

To activate Kakao Login,

1. Go to [My Application] > [Kakao Login].
2. Set 'State' to 'ON' under 🅐Kakao Login Activation on the Kakao Login page.

NOTE: Preview consent screen

After setting consent items, you can preview the Consent screen as configured in consent items by clicking 🅒Preview the Consent screen.

OpenID Connect Activation

If you want to integrate Kakao Login with OpenID Connect, you must also set 'State' to 'ON' under 🅑OpenID Connect Activation.

Set Redirect URI Required

A Redirect URI is an essential factor in serving Kakao Login service because the Kakao server and a service server exchange information through the Redirect URI to proceed Kakao Login based on OAuth 2.0.

The Kakao server passes authentication information needed for a service to Redirect URI, and the service proceeds the information received through Redirect URI to makes the next request. If Redirect URI is not specified, an error occurs when logging in with Kakao.

You can set Redirect URIs in [My Application] > [Kakao Login] > [Redirect URI]. When you register Redirect URIs, you must comply with the following rules:

• Redirect URI supports HTTP (80 port) and HTTPS (443 port) protocols.
• You must add HTTP and HTTPS schemes separately since the Redirect URIs are sensitive to HTTP and HTTPS protocols.
• You can set Redirect URIs up to 10. To set more than 10 Redirect URIs, request permission by referring to FAQ or set wildcard subdomains.

You MUST NOT specify parameters in Redirect URI path. If you need to keep or send specific information, use state value by referring to Kakao Login > REST API.

Manage consent items Required

To use the personal information of a user who is logged in with Kakao Account for your service, you need user's consent to access personal information and permission. When users log in with Kakao, they can choose what to provide to your service by consent item. Then, Kakao provides your service with the personal information that users agree to provide as you request Kakao APIs such as the Retrieving user information API.

How to

You can configure consent items needed for your service under 🅐Personal Information and 🅑Permission in [My Application] > [Kakao Login] > [Consent items]. You can check how the Consent screen would look in advance by clicking 🅒Preview the Consent screen.

To enable a scope, click [Set] and then set detailed options.

🅐 Select the content type for the corresponding user information.

• Required consent: Select this option when your service must get consent to the scope to use your service.
• Optional consent: Select this option when you want to allow users to consent optionally. Users may agree to provide the corresponding information when they log in with Kakao Account. If the user has not agreed when logging in, the user is asked to consent again when a service needs the information.
• Consent during use: Select this option when you want to ask permission when the consent is required, instead of asking when a user logs in. The scope with this option is not included on the Consent screen prompted when a user attempts to log in. If you request additional consent for the scope at the moment when the user information is required, you can get the consent.
• Not request consent: Select this option when your service does not need user's consent.

🅑 Provision after collecting information through Kakao Account: If you select this option, Kakao requests the user to input the data and provides it to your app when a piece of specific user information has not been saved in a user's Kakao Account. See Provision after collecting information for more details.

🅒 Purpose of consent: Specify the reason why you need to collect user data. The purpose is not displayed on the Consent screen but used for a review to grant permission.

After the settings, click [Save]. The consent items, except for the ones set as 'Not request consent', are presented to users when they log in on the Consent screen with checkboxes and phrases asking to provide their personal information. The items set as 'Required consent' are displayed as ⓐ[Required], and the items set as 'Optional consent' are displayed as ⓑ[Optional] on the Consent screen.

Consent types

There are three types of consent items. When you configure consent items, you can set a consent type for each scope. Then, the consent screen is displayed differently as specified.

Type	Description
Required consent	Users must consent to provide the corresponding information to use your service. Kakao asks permission when a user logs in with Kakao Account through the Consent screen. NOTE: Only the profile information can be set as 'Required consent' as a default. If you apply Kakao Sync, you can set more consent items to 'Required consent'.
Optional consent	Users can decide whether to consent to provide the corresponding information. Kakao asks consent when a user logs in with Kakao Account. Even when the user does not consent, the user can complete the login. If you use the Requesting additional consent API, you can ask consent again when the user information is needed.
Consent during use	Kakao asks permission in the middle of using the service, instead of requesting consent when a user logs in. You can get consent to the scope set as 'Consent during use' by specifying the scope parameter through the Requesting additional consent API. Then, the Consent screen with the scope added as a [Required] is prompted when the scope is required.

Provision after collecting information

If Kakao does not retrain specific user information, the corresponding scope is not displayed on the Consent screen during Kakao Login and you cannot retrieve the user information by requesting APIs that provide user information.

If your service must obtain consent to certain user information, set its scope to 'Required consent' and select the 'Provision after collecting information through Kakao Account' option (Provision after collecting information in short). Then, Kakao asks the user to input the data through the Consent screen during the Kakao Login process, and the user must consent to provide the information to complete Kakao Login, which prevents required information from missing consent.

This option can also be applied for the scopes set as 'Optional consent' or 'Consent during use' along with the Requesting additional consent feature for the case that a user has not consented through the Consent screen when the user attempts to log in. Then, Kakao requests permission when the information is needed during the use of the service.

Here is a sample screen that requests a user to input additional information.

This option is not applicable for the following scopes:

Consent Item	Scope ID	Note
Profile Info(nickname/profile image) Nickname Profile image	profile profile_nickname profile_image	User's profile information is automatically input when a user logs in with Kakao Account.
Phone number	phone_number	Kakao provides a phone number by obtaining it from the one saved in Kakao Talk, not by collecting it separately. For users who do not use Kakao Talk, you must collect their phone numbers separately in your service if phone numbers are required.

Personal Information

This table shows the scopes under 'Personal Information' in [My Application] > [Kakao Login] > [Consent Items].

You must enable each scope to use the corresponding APIs. If you want to extend its consent type for a scope, you may need to change the app settings or request additional permission.

Consent Item (scope ID)	API	Available consent type by default
Profile Info (profile)	Retrieving user information Retrieving Kakao Talk profile Retrieving Kakao Story profile	Required consent Optional consent Consent during use
Nickname (profile_nickname)	Retrieving user information Retrieving Kakao Talk profile Retrieving Kakao Story profile	Required consent Optional consent Consent during use
Profile image (profile_image)	Retrieving user information Retrieving Kakao Talk profile Retrieving Kakao Story profile	Required consent Optional consent Consent during use
Email (account_email)	Retrieving user information	Optional consent Consent during use To set to 'Required consent': Switch to Biz app.
Name	Retrieving user information	None. To set to 'Optional consent': Connect app to channel To set to 'Required consent': Review for Provision of Personal Information.
Gender (gender)	Retrieving user information	Optional consent Consent during use To set to 'Required consent': Review for Provision of Personal Information.
Age range (age_range)	Retrieving user information	Optional consent Consent during use To set to 'Required consent': Review for Provision of Personal Information.
Birthday (birthday)	Retrieving user information Retrieving Kakao Story profile	Optional consent Consent during use To set to 'Required consent': Review for Provision of Personal Information.
Birthyear (birthyear)	Retrieving user information	None. To set to 'Optional consent': Connect app to channel To set to 'Required consent': Review for Provision of Personal Information.
Phone number (phone_number)	Retrieving user information	None. To set to 'Required consent': Connect app to channel.
Connecting Information (account_ci)	Retrieving user information	None. To set to 'Required consent': Review for Provision of Personal Information.
Friends List in Kakao Service (Including profile image, nickname, and favorites) (friends)	Retrieve list of friends	Optional consent Consent during use Not allowed to set to 'Required consent'. IMPORTANT: Allowed to retrieve team members only. To retrieve all friends, permission is required.
Kakao Talk Channel addition status and details (plusfriends)	Check Kakao Talk Channel relationship	None. To set to 'Required consent': Connect app to channel.
Shipping information (shipping_address)	Retrieve shipping address	None. To set to 'Optional consent': Connect app to channel. To set to 'Required consent': Review for Provision of Personal Information.
KakaoStory Profile URL (story_permalink)	Retrieving Kakao Story profile	Required consent Optional consent Consent during use

If a user has not agreed to the consent item required for your service, an error occurs. In this case, request additional consent. For the consent items required for your service, you must set it to 'Required consent'.

Permission

This table shows the scopes under 'Permission' in [My Application] > [Kakao Login] > [Consent Items]. These scopes are allowed to set 'Optional consent' or 'Consent during use' only. If you set a scope to 'Optional consent', users are asked to consent to the scope when they log in. If you set it to 'Consent during use', users are asked to consent when the consent is required in the middle of using your service.

You must enable each scope to use the corresponding APIs.

Consent Item (scope ID)	API	Available consent type by default
Read access to KakaoStory posts (story_read)	Kakao Story > Retrieve story	Optional consent Consent during use Not allowed to set to 'Required consent'.
Publish posts in KakaoStory (story_publish)	Kakao Story > Post story	Optional consent Consent during use Not allowed to set to 'Required consent'.
Send message in KakaoTalk (talk_message)	Kakao Talk message	Optional consent Consent during use Not allowed to set to 'Required consent'. IMPORTANT: Allowed to send messages to team members only. To send to all Kakao Talk friends, permission is required.

If a user has not agreed to the required permission, an error occurs. In this case, request additional consent.

Kakao Talk Channel Optional

Set a representative channel

To allow users to add your Kakao Talk Channel connected to your app when logging in, you must set a representative channel as follows:

1. Register your service's business registration number to switch your app to a Biz app.
2. Switch your Kakao Talk Channel to a Business channel so that users can allow to add your Kakao Talk Channel on the Consent screen.
3. Connect your Biz app and Business channel set in Step 1 and Step 2.
4. Go to [My Application] > [Kakao Login] > [Kakao Talk Channel], and then click [Select a representative channel].
5. Select one of the business channels connected to your app as a representative channel to be displayed on the Kakao Login Consent Screen.

You can set only one representative channel among the connected business channels.

To change the representative channel, click [Modify] and select another business channel.

The specified representative channel is displayed on the Kakao Login Consent screen as follows.

Checking Kakao Talk Channel relationship

To use the Checking Kakao Talk Channel relationship feature, you must get consent from users. To do so,

1. Go to [My Application] > [Kakao Login] > [Consent Items].
2. Set 'Kakao Talk Channel addition status and details' to 'Required consent' or 'Optional consent'.

Transfer Personal Information Overseas

This setting is required for the service that transfers users' personal information overseas.

According to Personal Information Protection Act, Article 39-12 (Protection of Information Transferred Overseas), if your service provides, outsource the processing of, or transfers users' personal information obtained through the Kakao APIs to other countries, you must notify users of the followings in advance and obtain user's consent to transferring personal information overseas.

• Particulars of the personal information to be transferred
• The country to which the personal information is transferred, transfer date and method
• Name of the entity to which the personal information is transferred (For a corporation, the name of a corporation and the contact information of the person responsible for the management of information)
• The purpose of using personal information by the entity to which the information is transferred and the period of retaining and using personal information

Transferring personal information overseas means the following cases.

• If a domestic company (in Korea) intends to transfer user information stored in Korea to a third country.
• If an overseas company (outside Korea) intends to retrieve, store, or process the user information stored in Korea.

If your service corresponds to either of the cases above, you must register the information related to the transfer of personal information overseas.

1. Go to [My Application] > [Kakao Login] > [Transfer of Personal Information Overseas].
2. Click [Register Information].
3. Enter the required information.
   🅐 Country where personal information is stored: Enter the country where personal information is transferred to.
   🅑 Corporation name (company): Enter the name of a corporation to which the personal information is transferred.
   🅒 Contact: Enter the contact information such as email or phone number of the person responsible for the management of information, or customer center URL.

After registering the information above, the 'Consent to the Transfer of Personal Information to Foreign Parties' item is included as a Required item in the Consent screen. Users can see the detailed information which is registered in [Transfer of Personal Information Overseas] by selecting [view more] and consent to the transfer of personal information overseas.

Set unlink callback Optional

The Unlink callback is an optional function to send you a callback in the following situations:

• Users unlink their accounts with respective service apps in [Use Your Account] > [Manage Connected Services] on the Kakao Account page or in [General Settings] > [Privacy] > [Kakao Account] > [Manage Connected Services] on the Kakao Talk application.
• Users have not completed a signup process.

To use this feature, you can designate a URL to receive an unlink callback as follows:

1. Go to the [My Application] > [Kakao Login] > [Unlink], and click [Register Unlink].
2. Input callback URLs to receive and process a callback as a user requests unlink.

The unlink callback address only supports HTTPS over 443 port due to security issues since the request includes a Service user ID.

After the settings as described above, the Kakao server sends your service server the unlink callback when a user requests to unlink. To see the details on the callback request, refer to Reference Information > Unlink callback.

Depending on whether to use the Unlink feature, the buttons on the Manage Connected Services page are differently displayed.

If you disable the Unlink feature, the [Disconnect] and [Delete All Data] buttons are displayed on the Manage Connected Services page. In this case, users must request to unlink with [Disconnect] and request to delete user information with [Delete All Data] respectively.

If you enable the Unlink feature, [Delete All Data] is displayed only since the Kakao platform notifies your service of a user's request to unlink and deletes user information when the user selects this button.

User properties Optional

User property refers to a function to store some of service information in the Kakao platform. Kakao does not access and store the data in the service server but provides a feature to store some of user information on the Kakao platform and retrieve the information through the Retrieving user information API as needed.

To register property keys,

1. Go to [My Application] > [Kakao Login] > [User Properties].
2. Click [Add property key], and specify its name.

To update the user information, call the Storing user information API by passing the added or checked property keys with the user data.

• REST API
• JavaScript
• Android
• iOS
• Flutter

To check the updated user information, call the Retrieving user information API by referring to each development guide.

Reserved property keys

Here are the property keys assigned by default. Thus, you cannot use the same key names with the following keys. Besides the reserved keys, you can add up to 5 property keys more for each service.

• properties.profile_image
• properties.thumbnail_image
• properties.nickname

Security Optional

When you use a REST API, you can use a Client secret code to enhance security.

To use this feature,

1. In [My Application] > [Kakao Login] > [Security], click [Generate code], then a client secret code is generated.
2. Click [Set] in Activation state, and change the state to 'Use'.
3. When requesting the Getting tokens and the Refreshing tokens APIs, add the issued client secret code with the client_secret parameter.

Set Logout Redirect URI Optional

This is optional function used for ‘Logout of service along with Kakao Account’, an add-on feature to Kakao Logout. If you want to use this feature, go to [My Application] > [Kakao Login] > [Advanced] > [Logout Redirect URI] and set Logout Redirect URIs.

When you register Logout Redirect URIs, you must comply with the following rules:

• Logout Redirect URIs are allowed up to 10. If you want to register more than 10 URIs, ask DevTalk.
• Logout Redirect URI allows HTTP/HTTPS protocols and 80/433 ports.
• You must register HTTP and HTTPS protocols respectively as Logout Redirect URI is sensitive to schemes.

Refer to REST API guide to see how to leverage this feature.