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. If this tag is not attached, you can optionally apply the setting 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 optional functions.

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.

Advanced: Activate OpenID Connect

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 because 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.

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.
Create, retrieve, edit/delete Talk Calendar and events	Talk Calendar	Consent during use Not allowed to set to 'Required consent'. To set to 'Optional consent', request permission. IMPORTANT: To create or manage a public event or subscribed calendar, permission is required.

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

Set Kakao Talk Channel

Create a new Kakao Talk Channel

If you have not created any Kakao Talk Channel, create a new one as follows:

1. Select '새 채널 만들기(Create a new Channel)' in the Kakao Talk Channel Admin Center.
2. Set 채널 이름(Kakao Talk Channel name), 검색용 아이디(ID for search purpose), 카테고리(category), and other information.

After creating an new Kakao Talk Channel, request for upgrade the channel to a Business channel. Make sure to log in to Kakao Talk Channel Admin Center with the account that has a Master role of Kakao Talk Channel to be connected to a Kakao Sync service.

For more details, refer to Creating a channel(채널 만들기) in Kakao Business.

Upgrade to Business channel

To use Kakao Sync, you need to upgrade your Kakao Talk Channel to a Business Kakao Talk Channel (hereinafter referred to as 'Business Channel') by registering a business registration number. Only the Master account that creates the Kakao Talk Channel can upgrade to a Business channel.

1. Log in Kakao Talk Channel Admin Center with the Master account that refers to a Kakao Account used to create the channel.
2. In [채널(Channel)] menu at the top, select the Kakao Talk Channel that you want to upgrade to a Business channel, and then click [신청하기(Apply)] in [관리(Management)] > [비즈니스 채널 신청(Apply Business Channel)].
3. For the request, submit the following certificates:
   - Certificate of Business Registration
   - Certificate of Employment or ID card of Representative
   - Registration certificates (only for a mail-order business, medical device sales, and health functional food sales business)

After you request a review, it takes 3 to 5 days in business days for approval. If the information of the channel does not match the documents you submitted, or you have not submitted the required document, your request may be rejected. Refer to Business Channel Request Guide for more detailed information.

Set a primary channel

To allow users to add your Kakao Talk Channel connected to your app when logging in, you must set a primary 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 primary channel].
5. Select one of the business channels connected to your app as a primary channel to be displayed on the Kakao Login Consent Screen.

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

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

The selected primary channel is displayed on the Kakao Login Consent screen as follows.

Check 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'.

Set Simple Signup

The Simple Signup function enables users to easily sign up for the service by consenting to all terms required for your service at once on the Simple Signup Consent screen.

Conditions

You can activate the Simple Signup function to manage the terms in the following conditions:

• Your Biz app must be connected to the Biz channel with the same business registration number registered. Refer to Set up Kakao Talk Channel.
• Your app must pass the Review for Provision of Personal Information. Refer to Apply Kakao Sync.

After turning Simple Signup to ON, you can add a new term or manage the registered term. Note that at least one term must be registered to add or manage the terms.

Add a new term

You can register a new Terms of Service by clicking [Add a Terms of Service] in the 'Simple Signup' section.

🅐 Term's title: Input the title of Terms of Service both in Korean and English. The Terms in English are used when a language on a user device is set to English. Even though you do not have the English version of Terms, you should input at least the English title with alphabets, numbers, space, and special characters only available to type with a keyboard. (100 characters allowed) 🅑 Term's URL: Input the URL of a web page where Terms of Service can be checked. For optional Terms, you do not have to input URLs. 🅒 Term's condition: Select either 'Required consent item' or 'Optional consent item'. For the Required consent item, users must consent when signing up. For the Optional consent item, users can consent optionally or additionally according to services. 🅓 Term's TAG: Tags are used to check the consented status by Terms in Check the consented terms and required to use Getting consent to desired terms feature. You can add the tags that can be used for actual service development. For tags, you can only enter alphabets, numbers, hyphen(-), and underscore(_). It is recommended to input tags in Keyword_date, Keyword_order of Terms format.

When you register a new term, the term is set to inactive status by default. Thus, to use the term in your service, you must activate the term by clicking [Activate].

You can preview the Consent screen to be displayed in the actual service by clicking [Preview the Consent screen]. If there is any missing or incorrect information, modify the terms.

Manage registered terms

🅐 Activate/Inactivate: Select whether to display each term on the Simple Signup Consent screen. For the term that you do not want to use, click [Inactivate] on the upper right corner of the term. Conversely, click [Activate] if you want to make the previously registered term displayed on the Consent screen. 🅑 Modify: To modify the terms that have already been registered, click [Modify] on the upper right corner of the term you want to modify. Only when there is a change compared to the existing registered information, the [Save] button is activated. 🅒 Change order: To change the order of the terms displayed on the Simple Signup Consent screen, click [Change Order] on the right side of the 'Simple Signup' section, and then select a number for each term's order. After setting the orders, click [Save].

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

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 must designate a callback URL to receive unlink callbacks. Ensure that the unlink callback address only supports HTTPS over 443 port due to security issues because the request includes a Service user ID.

1. Go to the [My Application] > [Kakao Login] > [Unlink], and click [Register Unlink].
2. Set a callback URL to receive and process callbacks that are sent when users request to unlink from your app.
   🅐 Domain: Input a site domain used to receive callbacks. The domain for unlink callback supports HTTPS only.
   🅑 Method: Select a method to request callbacks between GET and POST.
   🅒 Callback: Input a path used to receive callbacks.
3. Implement a function to receive and process the callback request that the Kakao server has made by referring to Reference Information > Unlink callback.

After setting the unlink callback, you can see the detailed callback information under 'Unlink callback settings' and 'Enabled' in 'Status' as follows:

You can 🅐delete or 🅑modify the registered unlink callback information.

You can also disable the unlink callback function for a while. To disable this function, click 🅒[Set] in 'Status' and then select the [Disable] option in the Activate Callback dialog. Only the Owner or Editor account can disable this function.

Depending on whether to use the Unlink feature in your service, the buttons on the Manage Connected Services page are differently displayed to users. See Disconnect vs. Delete All Data.

Manage user properties

To store user data required for your service, add a custom user property. 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. You can add up to 5 property keys more for each service besides the reserved keys.

🅐 Account information: Shows the ID, linked status, and linked date of the team members who are linked to your app. 🅑 Reserved property: Shows the property keys assigned by default. You cannot use the reserved property keys as a property key name. 🅒 User property: Shows the custom user property keys that you added. The property values are displayed in the column of the corresponding team member.

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.

Enhance security

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

This is optional function used for Logout of service and 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 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.
• You can register up to 10 Logout Redirect URIs. If you want to register more than 10 URIs, ask DevTalk.

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