This document provides frequently asked questions and troubleshooting tips for adopting, configuring, integrating, and operating Kakao Sync.

If an error occurs while integrating Kakao Sync, or if the Consent screen, user information, or channel addition item you expect is not displayed, check the items below first.

If the issue continues, gather the following information and contact DevTalk.

• App ID
• Platform or hosting service in use
• Service URL
• Error code and the full error message
• App key and redirect_uri used in the actual request
• The problematic field in the Retrieve user information API response
• App user ID (service user ID) of the user experiencing the issue
• Search ID of the Kakao Talk Channel you want to connect to the Biz app

KOE006 occurs when the Redirect URI setting is incorrect, or when you request an authorization code with a redirect_uri value that is not registered in the app.

Check in the following order.

1. Check the redirect_uri value shown on the error screen or in the actual request log.
2. On the app management page, go to [App] > [Platform key] > [REST API key] or [JavaScript key] > [Kakao Login Redirect URI] and check whether the same URI is registered. (See Redirect URI).
3. Check that the protocol, domain, port, path, and trailing slash (/) match exactly.
4. If you use both the JavaScript SDK and the REST API, check that a Redirect URI is registered for both the JavaScript key and the REST API key. You can check and edit the Redirect URI by selecting [Edit] under [App] > [Platform key] > [REST API key] or [JavaScript key].

You can also check the redirect_uri used in the actual request on the error screen, and—if the error persists—in the email and notification that are sent, as well as in your service request logs.

If you use a hosting service, the actual callback URL used by the hosting service may be requested instead of the callback URL you entered in your service. Check the hosting service admin page as well.

Typical hosting service callback URI formats are as follows. Register them to match your actual service domain and hosting service settings. When using Kakao Sync through a hosting service such as Cafe24 or Godomall, the callback URI may differ by PC, mobile, HTTP, and HTTPS domain.

For a detailed error description, see the DevTalk KOE006 FAQ.

KOE010 or Bad client credentials usually occurs when client authentication information is incorrect in a token request.

Check in the following order.

1. On the app management page, go to [App] > [Platform key] > [REST API key] and check whether Client secret is enabled.
2. If Client secret is enabled, check whether you included the client_secret parameter in the Get token API.
3. Check whether the client_secret value in the request matches the value currently issued for the app.
4. Check whether the Content-Type of the token request is application/x-www-form-urlencoded.
5. Check whether the token request uses the POST method. Do not send the request as a JSON string or multipart/form-data.

Hosting service Simple Setup options such as Cafe24 may not support Client secret. If KOE010 or Bad client credentials occurs on a hosting service, change Client secret to [Disabled] or delete it, then check again.

Even for a consent item set as [Required consent], the Retrieve user information response may not include a value. [Required consent] means the user must consent to providing that item to continue signup. It does not mean Kakao creates and provides a value that does not exist in the Kakao Account.

Check in the following order.

1. In the Retrieve user information API response, check the required fields and the ${FIELD_NAME}_needs_agreement values.
2. Check whether the user's Kakao Account has the corresponding information.
3. Check whether the consent item supports Provision after collecting information through Kakao Account.
4. If the app does not have permission for the consent item, or you cannot set the required consent level, request additional features for personal information consent items.
5. If Kakao cannot provide the information, handle it in your service by collecting it directly, verifying it yourself, or guiding the user that signup cannot continue.

A phone number cannot be provided for a Kakao Account that is not linked to Kakao Talk, and Provision after collecting information through Kakao Account is also not supported. If name or CI is required, check whether the user has completed identity verification for the account.

If email is missing from the response, also check the following.

• If email_needs_agreement in the Retrieve user information response is true, request email provision consent again with Request additional consent for consent items.
• If an existing user logged in before the email consent item was configured, the existing token may not have permission to provide email. Guide the user to log in again or provide additional consent.
• To require email at login, you may need Switch to a Biz app and permission for consent item settings.

If you called the Get consent to desired service terms API but the Consent screen is not displayed, check the following two conditions.

• The requested service terms must be registered as [Required consent] in Simple Signup settings.
• The user must not have consented to those service terms yet.

If you request only terms the user has already agreed to, or only optional terms, the Consent screen is not displayed. Check the user's service terms consent status with the Retrieve consent details for service terms API.

If the Kakao Talk Channel addition item is not displayed on the Kakao Sync Consent screen, check the following.

• Check whether a Kakao Talk Channel is connected to the app.
• Check whether a primary channel is set.
• Check whether the user has already added the channel as a friend.
• Check whether the user logged in with a Kakao Account that is not linked to Kakao Talk.
• If your service needs to check the channel friend status, use the Check Kakao Talk Channel relationship API.

The channel addition item is optional for the user. If channel friend addition must be a condition for service signup, prepare separate guidance and a user flow that match your service policy.

Even if a user completes Kakao Sync Simple Signup, service signup is not complete if the user is not registered as a member in your service database.

Check whether the following flow is implemented.

1. Issue a token with the authorization code.
2. Call the Retrieve user information API with the access token.
3. Check required service terms consent status with the Retrieve consent details for service terms API.
4. Check whether the user is an existing member in the service database.
5. If the user is new, create a member. If there is an existing Kakao Login user or existing service member, first design Checking and linking existing members to prevent duplicate signup.
6. Issue a service session and complete login.

For the detailed implementation steps, see Kakao Sync Simple Signup process.

In a Kakao Sync service, if a user deletes their account but the link between the service and the app is not unlinked, the service may continue to appear in Manage connected services for the Kakao Account.

When a user deletes their account, handle both of the following.

• Delete the user information from the service database, or take actions according to your service terms and Privacy Policy.
• Call the Unlink API to unlink the app from the user.

To handle cases where the user unlinks first from Manage connected services in the Kakao Account, set the Unlink webhook.

You can configure this in the Kakao Business Partner Center after logging in with the channel's Master or Manager account.

For detailed setup steps, see the Kakao Business guide.

On the app management page, go to [App] > [Kakao Talk Channel] > [Primary channel] and change the desired channel to the primary channel.

You can select a primary channel from the Business channels connected to the app.

You can connect an app and a channel only when all of the following conditions are met. If they are not met, the channel is not displayed in the list of connectable channels.

• The channel must pass Business channel review. If it has not passed review, request conversion to a Business channel in the Kakao Talk Channel Partner Center.
• The business registration number saved in the Biz app must match the business registration number saved in the Business channel.
  • If the Business channel does not have a business registration number saved, register business information in the Kakao Talk Channel Partner Center.
  • To change business information, go to Kakao Business > [비즈니스 설정(Business settings)] > [사업자 정보 관리(Manage business information)].
• You must have administrator permission for both the app and the channel.
  • The Kakao Account that owns the Biz app must have the Editor or Owner role.
  • The Kakao Account that owns the Business channel must have the Master or Manager role.
• A Business channel can be connected to only one Biz app, so a channel already connected to another app is not displayed. Check that the Business channel you want to connect is not already connected to another app.
  • For how to connect an app and a channel, see Connect a Kakao Talk Channel to an app.
• You cannot connect a Business channel that is dormant, sanctioned, or pending deletion.

The Kakao Talk Channel addition item is a consent item that the user can choose. If your service must require channel addition as a signup condition, do not force it only through the Kakao Sync Consent screen. Prepare separate guidance and a signup flow that match your service policy.

If the channel addition Consent screen is not shown, or the actual channel friend status differs from what you expect, check Channel addition item first. If your service needs to check the user's actual channel friend status, use the Check Kakao Talk Channel relationship API.

If the business registration number (or unique number) of a business using Kakao Sync is found to be closed or suspended in a National Tax Service lookup, or if the business type is not eligible for a Business channel application, the Kakao Talk Channel may be switched to a general channel. In this case, you can request Business channel re-review in the Kakao Talk Channel Partner Center. Until approval, you can configure only limited consent items.

See Apply for a Business Channel. For other inquiries, contact the Kakao Sync Customer Center.

No. After Simple Signup is applied, the Simple Signup Consent screen or an additional consent screen may be displayed during login only when your service requires consent to required consent items or service terms.

Users who have already consented to all required consent items and service terms may not see the Consent screen again.

The Simple Signup Consent screen is not always displayed only because specific information such as email or name is missing from the Kakao Account.

In other words, whether an additional Consent screen is displayed depends on the consent items requested by the service, the user's existing consent status, service terms settings, and more.

No. Kakao does not access your service data. Kakao only receives API requests from your service and, based on those requests, provides information or performs internal platform processing.

Yes. You can test with a test app without affecting your operating service. For how to use a test app, see Test app.

No. If you already have a Biz app with Kakao Login integrated, do not create a new app. Adopt Kakao Sync with the existing app your service is using.

Because each app has different app keys, permissions, and user identifiers, adopting Kakao Sync with a new app requires existing Kakao Login users to log in or sign up again, and a different service user ID is issued. In that case, it becomes difficult to identify customers who signed up with existing Kakao Login by app user ID.

No. Applying Kakao Sync to the app you already use does not affect existing features. You can continue using features you already use, such as Kakao Login, Map, and Kakao Talk Share.

To connect a Developers app and a Kakao Talk Channel, the business registration number saved in the Biz app must match the business registration number saved in the Business channel.

You can change business information in Kakao Business > [비즈니스 설정(Business settings)] > [사업자 정보 관리(Manage business information)]. If you have difficulty changing it, contact the Kakao Sync Customer Center.

Even if you change business information, existing features such as Kakao Login, Map, and Kakao Talk Share are not affected.

• Users who logged in with the previously connected app cannot log in after the app is changed. When the app is changed, the service user ID changes and the user is processed as a new signup.
• Biz plugins used in the previously connected app can no longer be used.
• If you were using a chatbot, check whether any features depend on the app.
• Changing the app does not affect the channel's friends.

Among the Kakao Account user information your service receives, check which items can be used as clues to find the same user in your existing member information. Email or phone number is commonly used, but users can change them at any time, so they may not be suitable as identifiers.

In this case, we recommend using the service user ID, the user identifier provided by the Kakao platform. When a user's Kakao Account is linked to your service, a unique numeric service user ID is issued. This value does not change even if the same user deletes their account and signs up again. However, for apps created before September 19, 2018 that do not use [Fixed user ID], the service user ID may change when the user unlinks and then links again.

Because each service has a different membership system, user flow, and policy, it is difficult for Kakao to provide a specific handling method. However, you should create rules and policies to map existing members with Kakao Sync users so that users are not confused. For details, see Mapping.

We recommend treating users who signed up with Kakao Login before Kakao Sync was applied as existing members, not as new members. For details, see Mapping.

Kakao Sync is an extended feature of Kakao Login, and if the user logs in with the same Kakao Account, the app's service user ID does not change. Based on the service user ID (id) in the Retrieve user information API response, check whether the user is an existing member. If the user matches an existing member, do not create a new member; process login as the existing member. At that time, your service can reflect newly provided Kakao Sync user information and service terms consent details in the existing member information.

If you want users who do not have signup-required information such as email or name in their Kakao Account to enter it in the Kakao flow, check whether the consent item supports Provision after collecting information through Kakao Account and configure it. In this case, your service can use existing member information it already has, or request additional input according to service policy.

If a user who signed up with Kakao Login before Kakao Sync already entered email or name during service signup, your service continues login after verifying that it is the same user based on existing member information and the service user ID (id).

No. Kakao Sync Simple Signup lets users sign up easily without going through multiple signup pages. However, depending on the service situation, you may need to obtain additional consent to service terms or collect additional user information. In that case, request consent or information directly on your service page after Kakao Login.

However, users may leave without completing signup during an additional information input step, so we recommend collecting additional information separately only when it is actually needed. For details, see Member registration.

To delete a Kakao Account, the user must first clean up all connected services. To detect users who attempt to delete their Kakao Account, set the Unlink webhook. After receiving the Unlink webhook from Kakao, your service can post-process the user's account. For the detailed specification, see Unlink webhook.

Yes. You can implement this with Auto-login from Kakao Talk. Depending on the user's signup status, you can show an appropriate screen for either the logged-in or logged-out state. This feature works correctly only in the Kakao Talk in-app browser.

Personal information consent items are reviewed based on your service's signup process. Check the following before applying.

Refer to the documents below, supplement your application, and apply again.

• Request additional features for personal information consent items
• Review checklist
• Q. Request for privacy consent items was rejected. What could be the reason?

The consent items and consent levels you can configure differ depending on the app status, whether it is a Biz app, whether a Business channel is connected, and whether you have additional feature permissions.

After checking the consent items and consent levels available in Available consent levels and Kakao Login Consent items, request additional features for personal information consent items if needed.

However, apply only information that is truly required for service signup as Required consent. For information that is optionally needed, we recommend applying as Optional consent or collecting it in a separate flow while the user uses the service.

Yes. After registering newly added or changed service terms as [Required consent], you can request consent again at the needed time by calling the Get consent to desired service terms API.

However, if you request only terms the user has already agreed to, or only [Optional consent] terms, the Consent screen is not displayed.

The service app and the Kakao Talk Channel are separate. Even if the link with the service app is unlinked, the Kakao Talk Channel friend status remains. If you receive a customer inquiry, guide the user to block the channel in Kakao Talk.

Check whether you completely deleted the user's information from the service member database when the account was deleted.

If it was not deleted, when the same Kakao Account user unlinks from the service and then links again, the same service user ID is issued. However, for apps created before September 19, 2018 that do not use [Fixed user ID], the service user ID may change when the user unlinks and then links again.

If preexisting user information remains, it may cause problems, so you must correctly delete the information of users who deleted their accounts according to your service policy and related laws.

If you configured Kakao Sync through a hosting service such as Cafe24, Imweb, or Godomall, some settings must be changed in the hosting service admin page, not in Kakao Developers.

Check the following.

• Check whether the shopping mall URL, service terms URL, and Privacy Policy URL in the hosting service admin page are up to date.
• Check whether the Kakao Sync or Kakao Login settings in the hosting service admin page were saved correctly.
• If you need to disconnect Kakao Sync or reconnect with a different app or channel, disconnect first in the hosting service admin page.
• If you cannot disconnect yourself, prepare the app ID or REST API key, shopping mall URL, and information about the channel to disconnect, then inquire.

For how to configure Kakao Sync in Cafe24, see the Cafe24 Kakao Sync setup guide.

First check whether the Kakao Sync or Kakao Login settings in the hosting service admin page were saved correctly. For shopping malls adopted through the Simple Setup popup, Kakao Sync settings are applied based on the shopping mall information sent by the hosting service. If you edit them directly in Kakao Developers, the hosting service settings and Kakao settings may diverge again.

If the change is still not reflected after saving, prepare the following information and contact the hosting service customer center.

• Shopping mall URL
• Kakao Developers app ID or REST API key
• Item you want to change
• Time you saved in the hosting service admin page, and any error message

If the hosting service asks you to confirm with Kakao, contact DevTalk with the same information.

If signup items or service terms configured in the Cafe24 admin page are not reflected on the Kakao Sync Consent screen, check the following.

• For signup items, check whether the detailed item display setting is turned on in the Cafe24 admin page. If it is not, only default items may be synchronized.
• Service terms must be configured and synchronized in the Cafe24 admin page, not in Kakao Developers.
• Check whether the Kakao Developers app and Kakao Talk Channel are connected.
• In the signup item or terms of use settings screen, select [Save] to synchronize again.
• If it is still not reflected, prepare the shopping mall URL, app ID or REST API key, save time, and error message, then contact the Cafe24 customer center. If you are told that Kakao confirmation is needed, contact DevTalk with the same information.

If you adopted Kakao Sync through the Cafe24 Simple Setup popup, the following settings must be edited in the Cafe24 admin page, not in Kakao Developers.

• Shopping mall URL.
• Service terms URL and Privacy Policy URL.
• Information items collected at shopping mall signup.
• Optional provision consent items.
• Whether Kakao Login or Kakao Sync is used.
• Disconnecting or reconnecting Kakao Sync.

If a message appears that you cannot edit directly in Kakao Developers, first check the Kakao Sync settings in the Cafe24 admin page. Domain additions and terms additions are also configured in the Cafe24 admin page and then synchronized.

Yes. If you complete Kakao Sync Simple Setup with the same app that was used for existing Kakao Login, existing users can log in with their existing accounts and continue using the service.

If you select a new app or create a new app to configure Kakao Sync, a different service user ID is issued and the user may be processed as a new user. Therefore, you must select the existing app.

The business registration number registered in Cafe24 must match the business registration number set in the Kakao Developers app for the app to appear in the list.

Check the following.

• Check whether the business registration number in the Cafe24 admin page is entered in the 000-00-00000 format.
• Check whether the Cafe24 and Kakao Developers business registration numbers match including the hyphen (-).
• Check whether the logged-in Kakao Account has administrator permission for the app.

This happens when you selected a different app from the one previously used, or created a new app, during Kakao Sync Simple Setup. If the app differs, even the same Kakao Account user receives a different service user ID and cannot be identified as an existing member.

In the Cafe24 admin page, save Kakao Login as disabled, then select the previously used app when configuring again. Users who already signed up with the incorrectly configured app may need to sign up again after you restore the settings to the existing app.

This message is handled by Cafe24.

It can occur when a Cafe24 member created through Kakao Login deletes their account in the shopping mall or is deleted by an administrator, and then logs in again with the same Kakao Account.

According to Cafe24 policy, if an account created through Kakao Login has been deleted, re-signup may not be possible. Check the member status and whether re-signup is allowed in the Cafe24 admin page or through the Cafe24 customer center.

This message is handled by Cafe24.

If you use Kakao Login and Kakao Sync through a hosting service such as Cafe24, you cannot use Client secret.

On the app management page, go to [App] > [Platform key] > [REST API key] and check whether Client secret is enabled for the REST API key in use. Disable or delete Client secret, then try again. If the same message continues after Client secret is disabled, contact the Cafe24 customer center.

Button image settings must be changed in the Cafe24 admin page. Ask the Cafe24 customer center about the setting location and how to apply it.

You can refer to the Kakao Sync design guide, or download resources from Resource download.

If you cannot disconnect Kakao Sync yourself in the hosting service admin page, prepare the following information and contact DevTalk or the Kakao Sync Customer Center.

• App ID or REST API key.
• Hosting service in use and shopping mall URL.
• Name or search ID of the Kakao Talk Channel to disconnect.
• Reason you cannot disconnect yourself in the hosting service admin page.

After disconnection is complete, select the app and channel to use again in the new hosting service or shopping mall and configure Kakao Sync. If you need to keep existing Kakao Login users, we recommend continuing to use the existing app whenever possible.

If you have existing Kakao Login or Kakao Sync users, we recommend keeping the existing app and channel. If you use a new app, the app keys and the user identifier (service user ID) change, so you cannot treat existing users as the same users.

Before migration, check the following.

• App ID and app keys used in the existing shopping mall.
• Whether the new hosting service supports Kakao Sync Simple Setup.
• Whether the business information of the existing app and the new shopping mall matches.
• Whether existing members' service user IDs can be migrated to the new shopping mall member data.
• Your service policy for how to map existing members.

If you cannot continue using the existing app, your service must separately implement existing member mapping and a re-consent flow. For details, see Mapping.

If they provide the same membership system and the same service, you can add a web domain and Redirect URI to one app and use them.

However, if different hosting services or shopping malls each operate a separate membership system, connecting one app to them at the same time is not recommended. Depending on which shopping mall the user signed up for, another shopping mall may start the signup process again, and during Simple Setup the consent items and service terms may change to the settings of the last connected hosting service.