Concepts

This document introduces Kakao Login.

Overview

Kakao Login

Kakao Login is a Social Login service based on OAuth 2.0 that enables users to access various services using their Kakao Account.

Users can conveniently login to services through Kakao Talk or Kakao Account. Service providers can securely receive verified user authentication information from the Kakao API platform without having to directly manage user credentials.

Kakao Sync

Kakao Sync is an extension of Kakao Login that simplifies the user service signup process. It provides the Simple Signup feature, allowing users to agree to the consent items and service terms at once on the Kakao Login Consent screen. For the details on implementation methods, see Kakao Sync Concepts.

Implementation Guide

This section explains how to integrate Kakao Login into a service.

1. Check service requirements 2. Register and configure an app 3. Integration development

• Developer Documentation
  • REST API
  • JavaScript
  • Android
  • iOS
  • Flutter
• REST API examples by programming language

Login

This section explains about the login functionality offered by the Kakao API platform.

Login is the process in which a user verifies authentication themselves and grants authorization to a service. When a user successfully logs in using Kakao Login, secure tokens are issued to the service. The service can include this tokens in requests to prove its authorization.

Service login process

This section explains the process of logging into the service using Kakao Login. See the sequence diagram and the step-by-step explanation below.

• Kakao Login

  1. When the user selects the Kakao Login button on the user client, the service requests an authorization code from the Kakao API platform server.
  2. The Kakao API platform server requests authentication from the user and, upon success, prompts the user with the Consent screen for authorization.
  3. After authorization is completed, the Kakao API platform server redirects the user to the redirect URI, including the authorization code.
  4. When the service requests a token using the authorization code included in the redirect URI, the Kakao API platform links the user with the service app and issues the user's token to the service.

• User verification and registration

  1. When the service requests the Retrieve user information API using the issued Token, the Kakao API platform server responds with the user's information.
  2. The service verifies whether the user is an existing member using the provided user information. Based on the result, the service either proceeds with user registration or directly processes the login.

• Service login

  1. The service server creates a login session for the user’s client.
  2. The user client completes the login process using the issued session and navigates to the logged-in service screen.

Authentication

Authentication is the process of verifying whether the user requesting access to an account is the actual owner. A common authentication method is verifying the user’s entered ID and password.

Kakao Login utilizes Kakao Talk or Kakao Account for user authentication. See the authentication process for each method below.

• Authentication via Kakao Talk

  1. Launch Kakao Talk on the user’s device.
  2. Authenticate the user using the Kakao Account linked to Kakao Talk.

• Authentication via Kakao Account

  1. Display the Kakao login screen in the user’s service environment.
  2. Authenticate the user using the entered Kakao Account information.

Kakao login API by development environment

Kakao Login provides authentication via Kakao Talk and Kakao Account, categorized by development environment, to support various service environments.

For JavaScript SDK Simple Login, authentication is first attempted via Kakao Talk. If Kakao Talk is not installed, authentication falls back to Kakao Account. Differences between selectable APIs for other development environments can be found in the Implementation method in the reference column of the table below.

Development environment	Kakao Talk authentication	Kakao Account authentication	Reference
REST API	-	Kakao Login	-
JavaScript SDK	Simple Login	Simple Login	-
Android SDK	Login with Kakao Talk (Recommended)	Login with Kakao Account	Implementation method
iOS SDK	Login with Kakao Talk (Recommended)	Login with Kakao Account	Implementation method
Flutter SDK	Login with Kakao Talk (Recommended) Login with Kakao Talk: Web (Recommended)	Login with Kakao Account Login with Kakao Account: Web	Implementation method

Authorization

Authorization is the process of obtaining user consent for the user information requiring consent or permission required features requested by the service to be provided by the Kakao API platform. The Kakao API platform does not grant access to resources that have not been authorized by the user.

The service can configure the Consent screen by setting the required consent items in the app. When Kakao Login successfully completes user authentication, it prompts the user for authorization via the Consent screen.

The user completes authorization by reviewing 🅐 Personal information provision notice on the Consent screen and agreeing to the required 🅑 Consent items for service use. Once authorization is completed, the service receives an authorization code for issuing a token.

Token

A token is a string that contains user authentication and authorization information. The service can request a token issuance using the authorization code obtained as a result of authorization. The issued token can be included in API requests to verify access to information or the permission to use specific features.

Kakao Login issues an access token and a refresh token in accordance with the OAuth 2.0 standard. When OpenID Connect is enabled, an ID token is additionally issued. For the details, see the token roles and expiration times table.

Token roles and expiration times

Type	Role	Expiration time
Access token	Included in API requests to authenticate the user and verify authorization	Android, iOS: 12 hours JavaScript: 2 hours REST API: 6 hours
Refresh token	Renews the access token without additional authentication	2 months, renewable from 1 month before expiration Important: A new refresh token is issued upon renewal, and the previous refresh token is revoked.
ID token	Provides user authentication information for login sessions; requires OpenID Connect activation	Same as the access token

Additional features

The following is a list of additional features related to Kakao Login provided by the Kakao API platform. For the details, see each document.

• Kakao Account easy login: Displays the account selection screen when Kakao Account Easy Login information is available in the browser.
• Auto-login from Kakao Talk: Automatically navigates a logged-in page when a user accesses the service page via the Kakao Talk in-app browser.
• Login regardless of status: Re-authenticates the user regardless of previous login status.
• Create Kakao Account before login: Requests Kakao Account signup before proceeding with Kakao Login.
• Request additional consent: Sends an authorization request specifying Consent items that the user has not yet agreed to.
• Provide login hint: Automatically inputs the provided ID value into the Kakao Account login page.
• Simple Signup: Includes service terms in the Kakao Login Consent screen during an authorization request.
• Get consent to desired service terms: Specifies service terms registered in the service app during an authorization request.
• Get ID token of OIDC: Issues an ID token that can be used instead of a login session.

Link

This section explains about Link, which indicates that a user has signed up for the service with their Kakao Account and is registered to the service app.

The Kakao API platform automatically links a user who logs into a service with Kakao Login for the first time to the service app and considers them as using the service. Features that require Kakao Login, provided by the Kakao API platform, are only available to users linked to the app. The service should check whether the user is an existing member and either proceed with signup for new members or perform mapping for existing members.

If a user no longer wishes to use the service, the service must process account deletion, including a request to unlink from the app.

For the details on app linking, see Service login process.

Verifying registered users

The service can check whether a user is an existing service member by below steps.

1. Request the Retrieve user information API using the token of the logged-in user.
2. Compare the provided Kakao Login user information with the existing service member information to determine if the user is an existing member. See the recommended criteria below.
   • If the service user ID matches, consider the user as an existing member.
   • If the user ID is different but the name, email, birthdate, and birth year all match, consider the user as an existing member.
3. Based on the verification results, proceed with the appropriate member registration process below.
   • If no user information matches
   • If only some user information matches
   • If all user information matches

If no user information matches

This is the member registration process when the Kakao Login user does not match any existing service member information.

1. Register as a new member.
2. Provide the user with the option to map to an existing service member account.

If only some user information matches

This is the member registration process when the Kakao Login user partially matches the existing service member information. (Example: When the user information matches multiple service member)

1. Provide the user with hints about the existing service member account and verify the account. (Example: Email authentication)
2. If the user successfully verifies the account, ask for their consent to map with Kakao Login.
3. If the user agrees to map, process the mapping with the service member account; if they decline, process through signup.

If all user information matches

This is the member registration process when the Kakao Login user information fully meets the existing member criteria of the service (Example: When an existing account matches both email and CI).

1. Provide the user with hints about the existing service member account and confirm their intention to map to Kakao Login.
   • Recommended account hints: Masked service member account ID, registration date, nickname.
2. If the user agrees to map, process the mapping with the service member account. If they decline, process through signup.

Member registration

The service should register a new user or map to an existing user based on the result of the verifing registered users.

Signup

Signup is the process of adding a user who logs in with Kakao for the first time as a service member.

Since the Kakao API platform link the app and the user at the time of token issuance, the signup process should be handled after the token is issued. If the service fails to process member registration, the user may have to go through the signup process every time they log in, causing inconvenience.

Mapping

Mapping is the process of registering Kakao Login information to an existing service account when a user logs in with Kakao for the first time. By mapping Kakao Login information, you can improve data consistency and accuracy, and users can seamlessly continue their existing usage history.

Before Mapping, the service must verify if the user wants to map to Kakao Login. If the user agrees to map, proceed with the steps below.

1. Map the service user ID to allow login to the existing service account via Kakao Login.
2. Update the service member information using Kakao Login user information, excluding the service user ID.
3. If additional user information is required for signup, request additional consent to obtain it from Kakao or collect it independently.

If the user does not agree to mapping, the service must register the user as a new member. Even if the user information matches existing member information, the user may not want to link accounts or the actual account owner may be different.

Account deletion

Kakao Login users who no longer wish to use the service can unlink their service app through the account deletion process or request unlink directly via the Manage connected services feature provided by the Kakao API platform.

Account deletion process

If a user who has been using the service via Kakao Login requests to withdraw from the service or unmap their Kakao Login, the service must include an unlink request in the account deletion process to unlink the app from the user. Upon receiving the unlink request, the Kakao API platform will revoke authorization, log the user out, and initiate the user information deletion process.

See the sequence diagram and explanation below.

• Unlink

  1. When a Kakao Login user requests account deletion or unmapping, the service requests the unlink API for the user to the Kakao API platform.
  2. The Kakao API platform server Unlinks the user from the app and then processes logout.
  3. After the unlink is complete, the Kakao API platform server returns the unlink result to the service server.

• Account deletion

  1. Upon receiving the unlink result, the service processes the user's account deletion.
  2. After completing the account deletion process, the service redirects the user to the service home.

Unlink

This section explains about Unlink, which unlinks the linked the service app from a user's Kakao account. Once unlinked, the Kakao Account can no longer access the service. For platform support and development documentation, see Supported Features.

Below are the reasons for unlink by requester. Note that there are cases other than the account deletion procedure provided by the service.

• If requested by the service: Request the Unlink API as part of the account deletion process.
• If requested by the user: Manage connected services, Kakao Account deletion, or customer support inquiry.
• If operated by the Kakao API platform: Unlinking users with incomplete signup.

For user-initiated or Kakao API platform-initiated unlinking, the service server can receive notifications by configuring the Unlink Webhook. It is recommended to use the Unlink webhook to synchronize the service's user status with the Kakao API platform.

Logout

Logout is a feature that invalidates the user's token issued for the service. If a logout request is successful, you can no longer request the Kakao API with that Kakao Login user's information. Since the Kakao Account login state in the web browser remains active even after logout, follow-up actions, such as redirecting to the service's initial screen, are required.

The process of logout depends on the authentication method used in the request, and the available authentication methods vary by development platform. For the details, see Logout process by authentication method.

Logout process by authentication method

Authentication method	Token expiration handling	Device logout	Supported development platforms
Access token	Only the access token used in the request	Only the device logged in with the access token used in the request	REST API Kakao SDK
Admin key	All tokens of the user	All devices logged in with the user's tokens	REST API

Additional features

Below is a list of additional features related to logout. For the details, see each document.

• Logout of service and Kakao Account: Provides a bridge page to logout from both the service and the Kakao account.

Webhook

A webhook is a feature that delivers information to the service when there is a change in a Kakao Login user's account status. This allows the service to verify the changes and take appropriate actions.

Below are the webhooks provided by Kakao Login:

• Unlink webhook: Sends relevant information to the service for the user's account deletion when the user's Kakao account is unlinked from the service app.
• Account status change webhook: Sends the service of account status changes, such as app link and unlink, password changes, and deactivation, to allow the service to respond accordingly.

Security

Below is a list of security-related documents for Kakao Login that can help enhance the safety of user logins when applied to a service. For the details, see each document.

• Client secret code: Configures the service to allow token issuance and renewal only when the pre-issued Client secret code is included.
• Parameters for security: Configures OAuth 2.0 and OpenID Connect standard security parameters.
• Allowed IP addresses: Allows only the registered IP addresses.
• Security guidelines: Provides security recommendations for services using the Kakao API platform.

Usage Policy

User information management

The Kakao API platform provides user personal information to services based on the consent for the Provision of personal information to third parties. Therefore, services bear full responsibility for managing the provided personal information and must strictly adhere to the following guidelines to securely protect and manage user information.

User information deletion when a user deletes the account

Services must irreversibly destroy all user personal information upon user's account deletion in accordance with the Kakao Developers Operating Policy. It is strongly recommended to verify user's account deletion status beyond the account deletion process using the Unlink webhook.

If personal information needs to be retained for a certain period after user's account deletion, explicit user consent is required. The service user ID (user_id) assigned when linking a Kakao Account with an app is also considered personal information and must be destroyed.

Collection and use of information

The service must collect only the minimum user information necessary to provide its functionality and use the collected information appropriately for its intended purpose. For the purpose of providing each user information item through the Kakao API platform, see user information.

User information may be changed or deleted. It is recommended to request the Retrieve user information API each time a user logs in to update the service's member information with the latest data.

Precautions for using email

The user email address information provided by the Kakao API platform should always be verified for validity and authentication status before use.

Invalid email addresses are partially masked (Example: ka***@kakao.com), which may limit their usability. Unauthenticated email addresses may not receive emails sent by the service. Additionally, since email addresses can be changed upon user request, using them as an ID or a criterion for determining the same user is not recommended.

Transfer of personal information overseas

According to Article 28-8 of the Personal Information Protection Act (Transfer of personal information overseas), when providing, outsourcing, or storing user personal information obtained through the Kakao API in a foreign country, the below items regarding the Transfer of personal information overseas must be disclosed to the user, and consent must be obtained in advance.

1. Destination country of the personal information transfer
2. Date and method of personal information transfer
3. Name of the recipient of the personal information (for corporations, the company name and the contact details of the data protection officer)
4. Purpose of personal information use by the recipient, as well as the retention and usage period

Cases where the transfer of personal information overseas applies include the following:

• When transferring and processing domestic user information by a foreign entity.
• When a foreign entity accesses, stores, or processes domestic user information.

For details on how to register transfer of personal information overseas, see Prerequisites.

Service terms management

The consent, inquiry, and revoke functions for service terms provided by Simple Signup are intended for expressing user intent to the service, not Kakao. Therefore, the service must recognize that the management and responsibility for the service terms of the app rest entirely with the service and operate in a way that prevents potential damages.

The content of the service terms registered in the app must be identical to the actual service terms and comply with relevant laws. If the registered service terms differ from the actual terms or do not comply with relevant laws, the service may be restricted.

Unlinking users with incomplete signup

Since December 28, 2020, the Kakao API platform has been unlinking users who have not completed service registration on a daily basis. The criteria for determining incomplete registration are as below.

• When using the Auto-link: If the service does not call a user information request API, such as Retrieve user information API, within 24 hours after the user's first Kakao Login.
• When using manual signup: If the service does not call the Manual signup API within 24 hours after the user's first Kakao login request, causing the user not to be linked to the service app.

Unlinking users with incomplete signup can be identified through the Unlink webhook. For the details, see the notice.

Social login policies by open markets

The belows describes the social login policies of major open markets that should be referred to when using Kakao Login in a service. For more details, see the usage policies of each open market.

Android

For services providing an Android app, Google Play policies require that users be provided with an in-app option to delete their app account and related data. Failure to comply with this policy after May 31, 2024, may result in additional corrective actions, including app removal from Google Play. For the details, see Understanding Google Play's app account deletion requirements.

iOS

For services providing an iOS app, Apple app review guidelines require that apps using social login must offer in-app options to unlink social login and delete the user account. This review guideline has been applicable to submissions since January 31, 2022. For the details, see App Review Guidelines.

Guide to utilize and prerequisites

In addition to the key aspects of Kakao Login introduced in this document, the following provides guidance on additional Kakao Login-related documents.

Utilize

For more effective use of Kakao Login, see Utilize. This section provides key supplementary information related to the core concepts explained above.

Prerequisites

Details on configuring Kakao Login are covered in Prerequisites. In that document, tags attached to section titles distinguish between required settings that must be configured and optional settings that can be adjusted as needed.

Additional documents

Additional documents are available covering various aspects of Kakao Login, including implementation methods for different development platforms (REST API, JavaScript, Android, iOS, Flutter), explanations and usage of supplementary features (Webhooks, Multi-App), as well as resources such as the Design Guide, FAQ, and Troubleshooting. For the details, see each document.

Supported features

• You can also check the support status of each API and feature for different development platforms in Scope of Support.

• The availability of each API and feature across development platforms can also be checked in the Scope of support.

APIs and Features		Description	Documentation
Kakao Login	Get authorization code	Calls the Kakao Login Consent screen and requests an authorization code after obtaining user consent.	REST API
	Get token	Requests the issuance of an access token and a refresh token using the authorization code.	REST API
	Simple Login	Operates the same as requesting an authorization code and is used in the Kakao SDK for JavaScript when requesting one.	JavaScript
	Login with Kakao Talk	Uses the Kakao account and authentication information linked to Kakao Talk to log in.	Android iOS Flutter
	Login with Kakao Account	Logs in by entering Kakao account credentials via the default browser.	Android iOS Flutter
	Kakao Account easy login	If easy login information exists in the browser, displays an account selection screen.	JavaScript Android iOS Flutter
	Auto-login from Kakao Talk	Immediately displays a logged-in page for service members when entering a service page via the Kakao Talk in-app browser.	REST API JavaScript
	Reauthentication login	Performs user authentication again regardless of the current login status.	REST API JavaScript Android iOS Flutter
	Login after Kakao Account signup	Prompts the user to sign up for a Kakao account and then requests login after sign-up is complete.	REST API Android iOS Flutter
	Request additional consent	At a desired point, specifies Consent items that the user has not yet agreed to and requests authorization.	REST API JavaScript Android iOS Flutter
	Provide login Hint	Automatically fills in the provided ID on the Kakao account login page during the login request.	REST API JavaScript Android iOS Flutter
	Get consent to desired service terms	Requests user consent for selected parts of the app’s terms of service.	REST API JavaScript Android iOS Flutter
	Set token	A feature provided by the Kakao SDK for JavaScript that assigns the token issued through Kakao Login to enable Kakao API calls.	JavaScript
	Check token presence	A feature provided by the Kakao SDK for Android, iOS, and Flutter to verify if a token issued during login exists.	Android iOS Flutter
	Retrieve token information	Verifies the validity of the access token or checks its details.	REST API Android iOS Flutter
	Refresh token	Refreshes both the access token and the refresh token.	REST API
Retrieve user information		Retrieves information of the currently logged-in user.	REST API JavaScript Android iOS Flutter
Retrieve multiple user information		Retrieves information for multiple app users.	REST API
Retrieve user list		Retrieves a list of user IDs for the app's users.	REST API
Store user information		Saves User property values.	REST API JavaScript Android iOS Flutter
Shipping address	Select shipping address	A feature provided by the Kakao SDK that opens a shipping address picker, allowing users to select an address and returns the selected address ID.	JavaScript Android iOS Flutter
		Retrieve shipping address	Provides either a specific shipping address corresponding to a shipping address ID or a list of all shipping addresses.	REST API JavaScript Android iOS Flutter
Retrieve consent details		Retrieves detailed information on the Consent items the user has agreed to.	REST API JavaScript Android iOS Flutter
Revoke consent		Revokes consent for items that the user previously agreed to.	REST API JavaScript Android iOS Flutter
Retrieve consent details for service terms		Verifies which terms of service the user agreed to during login.	REST API JavaScript Android iOS Flutter
Revoke consent for service terms		Revokes the consent for the terms of service that the user had previously agreed to.	REST API JavaScript Android iOS Flutter
OpenID Connect	OIDC: Retrieve Discovery document	Checks the OpenID Connect service provider settings for Kakao Login.	REST API
	OIDC: Get public key	Retrieves the list of public keys used by the Kakao authentication server to sign the ID token.	REST API
	OIDC: Get ID token information	Provides reference information for validating the ID token.	REST API
	OIDC: Retrieve user information	Retrieves the information of the currently logged-in user. Use this when OpenID Connect–compliant user information is required.	REST API
Logout		Expires both the access token and the refresh token.	REST API JavaScript Android iOS Flutter
Logout of service and Kakao Account		Expires the session of the Kakao account logged in on the web browser and logs out of the service as well.	REST API
Unlink		Unlinks between the app and the user's Kakao account.	REST API JavaScript Android iOS Flutter
Advanced: Set consent to service terms		Treats the user's consent for specific terms of service as granted.	REST API
Advanced: Manual signup		A feature that manually links the app with the user in apps where automatic linking is set to [Disabled].	REST API Android iOS Flutter
Unlink webhook		Sends a webhook to pre-registered URL when a user unlinks from a service app.	Callback Prerequisites
Account status change webhook		Sends a webhook to pre-registered URL when there is significant changes on a user's account.	Callback Prerequisites