Concepts

This document introduces Kakao Login APIs and their features.

Overview

The Kakao Login API enables users to log in to your app with their Kakao Accounts in a fast, simple, and secure way, which helps to retain users on your app and maximize the number of people using your app.

You can integrate Kakao Login into your service in the following cases. Note that the functions of creating and deleting users' accounts are not provided by Kakao. Thus, You must implement the functions in your service internally because Kakao does not access or modify service data, such as saving or deleting user information.

Kakao Login

Here are the functions required for Kakao Login:

Kakao Sync

Kakao Login enables users to sign up or log in more conveniently by linking their accounts to your service. If you want to increase the membership rate in your service or perform sophisticated target marketing according to users' demographic information, consider integrating Kakao Sync, an extended version of Kakao Login.

Kakao Sync provides the following two key features:

• Simple Signup: allows users to consent to all of the service terms, provision of personal information to third-party, and channel additions in the Consent screen without inputting information.
• Kakao Account information: allows you to leverage business solutions such as Kakao Talk Channel more effectively.

Login

When a user logins with Kakao, Kakao authorizes a third-party application ("app")A project associated with your service. An app is used to register your service information on the Kakao platform and get permission for the use of Kakao APIs. to access limited information. The authorization process with Kakao Login complies with Open Authorization (OAuth) 2.0, a standard authorization framework. For detailed specifications, refer to OAuth 2.0 Authorization Framework (RFC6749). If you want to implement Kakao Login for both authorization and authentication, you can use OpenID Connect (OIDC) protocol.

Login flow

Here is the login process based on OAuth authorization.

Token information

Tokens are used to verify a user's identification, allowing you to keep using Kakao APIs without additional verification. The Kakao SDKs have a built-in token management feature. On the other hand, if you use a REST API, you need to request extra APIs to retrieve or refresh the tokens.

Here are three types of tokens you can get when you integrate Kakao Login. The validity periods of tokens differ depending on the platforms, as described in the below table.

Authorization methods according to user environments

The Kakao Login API proceeds the authorization process differently according to platforms, user environments, or login flows as follows.

* 'Login with Kakao Talk' is only supported on the most commonly used web browsers such as Chrome or Safari.

* 'Login with Kakao Talk' is not supported on a mobile app using a REST API.

Auto-login from Kakao Talk

The Auto-login from Kakao Talk (Auto-login, for short) is an extended feature of Kakao Login, which allows users to log in automatically from Kakao Talk in-app browser, and shows a different page depending on the user's login status. This feature allows for a more efficient and convenient service for users according to their signup status when accessing your service page in the Kakao Talk in-app browser.

The Auto-login process is broken down into three steps.

Here is a sequence diagram showing the Auto-login process.

Here is one of the Auto-login scenarios. As an example, let's see a product page that is commonly shared through Kakao Talk.

• See the browser information to check if the user accessed the page through the Kakao Talk in-app browser.
• If the user has accessed the page through the Kakao Talk in-app browser, add prompt=none in the login request.
• If the user has signed up through Kakao Sync, you will get an authorization code and show a product description page in a logged-in state. In this case, users do not need to log in to buy the product on the page.
• If the user has not signed up, an error returns. In this case, show the user the product page in a logged-out state. If the user wants to log in to make a purchase, prompt the user to log in, not using the Auto-login feature.

Login hint

Login hint is a feature that automatically fills in a given value in the ID field of the Kakao Account login form. You can make login easier for users who logged in to your service with Kakao Login. Pass the login_hint or loginHint parameter when you request the authorization code to apply the login hint to your service.

Kakao Account easy login

Kakao Account easy login is a feature that provides the select account page when the browser has the user's easy login information. You can use Kakao Account easy login by requesting with prompt as select_account.

Users can check [Save Login Information] to save their login information on the browser. When Kakao Login is requested on the browser that has Kakao Account easy login information, the select account page is prompted. The user can log in with the selected account without ID and password.

Note: Login process with login hint

Kakao Login with login hint may differ the process. Refer to below.

You can request Kakao Login with both the login hint and the prompt parameter. The Kakao Login process with the prompt parameter is below.

Logout

To log a user out of your service, you can use the Logout API which invalidates the access token and the refresh token issued through the Kakao Login process.

The logout proceeds differently depending on how the Logout API is requested as follows:

After a user is logged out, you cannot call any Kakao APIs by using the expired access token in the service. You need to implement the subsequent process after a user is logged out of your service, such as redirecting the user to the main page or changing the user status.

Ensure that the Logout API enables users to log out of service only without affecting the Kakao Account login session. If you need to make users log out of their Kakao Accounts as well as your service, use the Logout of service and Kakao Account functionality.

Logout of service and Kakao Account

If you want to log a user out of both Kakao Account and a service where the user requests to log out, you can use the add-on feature, 'Logout of service and Kakao Account'. The basic Logout API invalidates the access and refresh tokens but Kakao Account login session is still retaiend. On the other hand, if you use the 'Logout of service and Kakao Account' feature, both of the Kakao Account session and the service session expire.

When a user attempts to log out in a service that this feature is applied, the user is redirected to a bridge page where the user can select between [Log out of this service] and [Log out of the service and Kakao Account].

The logout proceeds differently depending on the Kakao Account's login status and which option a user selects.

• If a user selects [Log out of this service], the user is redirected to the Logout Redirect URI set in [My Application] > [Kakao Login] > [Logout Redirect URI].
• If a user selects, [Log out of the service and Kakao Account],
  • If the Kakao Accout session is not retained, the user is redirected to the set Logout Redirect URI.
  • If the Kakao Accout session is retained, Kakao ends the Kakao Account session and redirects the user to the set Logout Redirect URI.

To implement the 'Logout of service and Kakao Account' feature in your service,

1. Register Logout Redirect URI which users are redirected to when the logout request is successful.
2. Develop 'logout of service and Kakao Account' feature by referring to REST API. This API invalidates the access token and redirects a user to the registered Logout Redirect URI. If a user selects [Log out of the service and Kakao Account] and the user's Kakao Account session is retaiened, this API also expires Kakao Account session.
3. Expire the user's service session in your server-side at the moment when the user is redirected to the Logout Redirect URI.

Link

The link indicates the connection status between a service and a user's Kakao Account.

When a user attempts to log in to a service with the Kakao Account for the first time, the user is asked to agree to provide personal information to a third party and service terms on the Consent screen. Once the user agrees to permit the service to access the user's personal data, the user's Kakao Account is linked with the service app.

Once the user is linked to a service,

• The user can use the service without going through an extra signup process.
• The third-party service can access user data or use Kakao services by calling the Kakao APIs with the tokens passed from Kakao.

Linking vs. Creating user account

Unlink

As opposed to the concept of link, the unlink functions to disconnect the connection between a service app and a user's Kakao Account.

How to handle unlink request

Depending on how users are unlinked, you need to procced differently as follows:

After unlink

After a user's account is unlinked from your app,

• You cannot make API calls associated with the user information.
• Users can re-link to your app by loging in with their Kakao Account.
  • After the re-link, the previous app usage history cannot be recovered.
  • After the re-link, the app issues the same service user ID for the user. If your service retains the user’s data under the service user ID, you can provide the same service for the user.
• According to the Kakao Developer's Terms of Service and Privacy Policy, you should handle users' Kakao Account information that they have provided to use your service.

Unlink on Manage Connected Services

Users can unlink their Kakao Accounts from services in [Settings] > [Kakao Account] > [Manage Connected Services] on Kakao Talk application or [Use Your Account] > [Manage Connected Services] on the Kakao Account page.

Disconnect vs. Delete All Data

Depending on whether the Unlink callback function is implemented in your service, the buttons on the Manage Connected Services page are displayed differently.

If you do not use the Unlink callback function, 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 use the Unlink callback function, [Delete All Data] is displayed only because the Kakao platform notifies your service of a user's request to unlink and delete user information when the user selects this button.

Each button functions as follows:

Managing service accounts

Creating service account

While the link between your app and Kakao Account is processed on the Kakao platform, the signup process to register as a new member with Kakao Account should be processed in the service database. Be sure that Kakao API just passes the result in response to your request or processes the information, not access your service data.

When a user agrees to provide the user data on the Consent screen, find a match for the user with the provided user data.

• For the existing users, link the user's account with your service.
• If a user is new to your service, you need to register the user data in your service database to create a new account.

In the signup process,

1. Decide what types of user data your service requires to use your service.
2. Check which data your service needs and which data Kakao provides. If Kakao does not retain specific data, collect it when a user signs up. However, this might cause a user to quit the signup process for the inconvenience, so collect the user data only when your service needs or a user attempts to use the related service if necessary.

Deleting service account

If a user requests to delete the service account,

1. Call the Unlink API to unlink the user's Kakao Account from your service app.
2. Delete the user information in the service database to terminate the user's service account.

If a user's service account is deleted, the user's Kakao Account also must be unlinked from the service. Otherwise, the Kakao platform considers the user is still using the service.

Handling Kakao Login users

If your service implements a sign-up process, you also need to implement a process to handle users who attempt to log in or sign up with Kakao Account.

For user's convenience, we recommend allowing users to log in with the existing user data through Kakao Login.

Here is a flow that shows how to classify users when linking the users with the existing user data stored in the service. Basically, all policies and processes related to managing users are determined by the service, but this flowchart would be helpful to provide users with a seamless and convenient signup process and use of the service.

Identify registered users

At the moment when a user attempts to link with your service, you can figure out whether the user has already been signed up.

You can check if Kakao retains the data of the new users by using some unique data such as Connecting Information (CI), phone number, or email. Then, map users by referring to Handle service members.

To check if a user is registered in a service that adopts Kakao Sync, the value of Connecting Information (CI) saved in Kakao Account is generally used. However, if your service does not collect CI, you can also refer to phone number, email, or birthday.

Handle service members

Depending on whether users' data is stored in the service database, you can handle the users differently as follows:

• If all user data matches
• If only some user data matches
• If no user data matches

Cautions when linking the existing user data to Kakao Account information

• Even though user data completely matches the existing user data, ask the user if the account information is the user's and proceeds to link the account. Some users may not want to link their accounts with Kakao Accounts, or user data may not belong to the user.
• Consider that the personal information provided by Kakao can be changed when designing and developing your service. Users may change their personal information such as birthday and gender in the account at any time and delete the Connecting Information (CI) value in Kakao Account if necessary. Or new information that is not passed when signing up may be passed additionally when a user logs in.

If all user data matches

If there is user data that matches Kakao Account information, notify a user of the registered status and ask the user to log in with Kakao using the existing account.

• If a user agrees to link with the existing account, add the Kakao Account information to the existing user data and allow the user to log in with Kakao using the existing account.
• If a user does not agree to link with the existing account, add the user's account in the service server's database as a new member.

If only some user data matches

If only some user data matches with Kakao Account information, it is recommended to link the user to the user's Kakao Account rather than registering as a new member.

Notify a user of the account that is assumed as the user account and link the user to the user's Kakao Account by asking the user to input the password.

Here is a representative example of one of the methods that link to existing user data.

If no user data matches

If user data that matches a new user account does not exist in your service database, create a new account for the user. However, the user may have been signed up previously for the service. For this case, you can request the user to input the existing account information to link with the existing account.

Provide 'Linking with my account' option

Some users who actively use your service may want to link the service accounts to their Kakao Accounts. Other users who use the service with other social media accounts may wish to link the accounts to the Kakao Account. For these cases, you can provide the '소셜 계정 연동 기능(Linking a social media account)' option in your service to link their service accounts to their Kakao Accounts through Kakao Login or Kakao Sync Simple Signup.

User consent

Kakao requests consent to the required user information when a user logs in with Kakao for the first time. After a user logs in Kakao, the user information stored on the Kakao platform can be provided to each service through Kakao APIs. Ensure that the user information is only available when users agree to provide their personal information to third-parties. If users do not agree, Kakao cannot provide the information when your app requests even though the user information is saved in Kakao Account.

Consent screen

When you request the Getting authorization code API or Login APIs through the Kakao SDKs, the Consent screen configured in [My Application] > [Kakao Login] > [Consent Items] is prompted to users as follows.

Scope

Scope refers to the data that your app can access through Kakao APIs. A scope is also referred to as 'consent item' on the Consent screen or user interface shown to end-users.

How to check scope ID

You can configure consent items needed for your service under 'Personal Information' and 'Permission'. Go to [My Application] > [Kakao Login] > [Consent items] page. You can check the 'Scope ID' column for each scope. You can also refer to Manage consent items > Personal Information and Permission.

When to use scopes

You can set the scopes when you want to specify the scopes to obtain consent by passing the scope parameter when you call the Login API or Requesting additional consent API. Refer to Scope parameter.

How to check which scope required consent

When you request the Retrieving user information API, the response includes ${FIELD_NAME}_needs_agreement with a boolean type provided along with each user information. The key is provided to inform that the scope requires consent for your app to access the data and only provided when the scope is enabled on the Consent Items page.

Here is a scenario according to the presence of the user information.

• If the user information is stored in Kakao Account, you can retrieve the information as far as the user has consented.
  • true returns: You can obtain consent to use the stored user information by Requesting additional consent.
  • false returns: The user information has already been providing so requesting consent is not necessary.
• If the user information is NOT stored in Kakao Account,
  • true returns: You can obtain consent through Provision after collecting information feature.
  • false returns: it is recommended not to use the user information. If required, you can collect it internally.

How to revoke consent to a scope

You can revoke the user's consent by calling the Revoking consent API.

This API is also called when a user withdraws the Optional consent items in [Settings] > [Kakao Account] > [Manage Connected Services] on the Kakao Talk application or in [Use Your Account] > [Manage Connected Services] on the Kakao Account page.

Request additional consent

The Requesting additional consent API is used to request permission from the users to provide their user information or to use some functions which are provided by the Kakao platform.

It is recommended to request consent to scopes at the moment when your service needs, rather than collecting all information when a user logs in.

Scope parameter

To request additional consent, adding the scope parameter when you request the Login API (or Getting authorization code API if using a REST API).

Whether to use the scope parameter and the user's linked status affect which API is invoked and which scopes are included on the Consent screen as follows:

If OpenID Connect is enabled, you must add 'openid' to 'scope' along with the scope values you want to obtain consent. If not, you cannot get an ID token even though OIDC is enabled because the OAuth protocol is applied.

Best practice

{
  "id": 1633204891,
  "connected_at": "2021-02-18T06:13:55Z",
  "properties": {
    "nickname": "춘식이",
    "profile_image": "http://k.kakaocdn.net/dn/DCjQu/btqti3A1gEc/zgip1O4JmSnG7CDfmKtTO2/img_640x640.jpg",
    "thumbnail_image": "http://k.kakaocdn.net/dn/DCjQu/btqti3A1gEc/zgip1O4JmSnG7CDfmKtTO2/img_110x110.jpg"
  },
  "kakao_account": {
    "profile_needs_agreement": false,
    "profile": {
      "nickname": "춘식이",
      "thumbnail_image_url": "http://k.kakaocdn.net/dn/DCjQu/btqti3A1gEc/zgip1O4JmSnG7CDfmKtTO2/img_110x110.jpg",
      "profile_image_url": "http://k.kakaocdn.net/dn/DCjQu/btqti3A1gEc/zgip1O4JmSnG7CDfmKtTO2/img_640x640.jpg",
      "is_default_image": false
    },
    "email_needs_agreement": true       // Requires consent to Email
  }
}

HTTP/1.1 403 Forbidden
{
  "msg": "insufficient scopes.",
  "code": -402,
  "api_type": "TALK_MEMO_DEFAULT_SEND",
  "required_scopes": [
    "talk_message"
  ],
  "allowed_scopes": [
    "profile",
    "account_email"
  ]
}

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "token_type":"bearer",
    "access_token":"${ACCESS_TOKEN}",
    "expires_in":43199,
    "refresh_token":"${REFRESH_TOKEN}",
    "refresh_token_expires_in":5184000,
    "scope":"account_email profile"     // Scope user has agreed to
}

User information

After a user logs in, you can request user information through the Kakao APIs, including the Retrieving user information API. Kakao provides user information as far as users agree to provide.

Here are the kinds of user information retrieved through the respective Kakao APIs:

• Data passed through the Retrieving user information API
• Data passed through other APIs

Data passed through the Retrieving user information API

You can retrieve the following user information through the Retrieving user information API. You can use the retrieved user information as member information in your service when the user logs in with Kakao Login or signs up through Kakao Sync Simple Signup. For the information that Kakao does not manage such as passport number, you must collect it separately in your service.

For detailed information including data types and formats, refer to REST API.

Data included in Kakao Account

Each user information of the Kakao Account includes a field whose name ends with needs_agreement, indicating whether user consent is required to provide the information. For more details, refer to needs_agreement.

Permission: Indicates the consent items that require permission to set as 'Required consent' or 'Optional consent'. Refer to Manage consent items to see how to obtain permission.

Cautions when using email

• If your service uses email provided by Kakao, you must check if users' email is valid through the is_email_valid field, which is provided along with email when a user consents to the Email scope.
  • If a user's email has expired, the user's email is masked with asterisks (*). (Example: ka***@kakao.com)
• If your service sends emails to the email addresses provided by users, you must check both the is_email_valid and is_email_verified fields.
• User's email saved in Kakao Account can be changed if a user wants. For this reason, we recommend not to use users' emails as an ID or not to identify users by email.

Data passed through other APIs

Permission: Indicates the consent items that require permission to set as 'Required consent' or 'Optional consent'. Refer to Manage consent items to see how to obtain permission.

Shipping address

The Kakao Login user's shipping address registered on the Kakao Account is provided through a REST API or Kakao SDK. Kakao SDK provides the shipping address picker to utilize in the service.

How to use

To use APIs for the shipping address,

• Set the [Shipping information] consent item.
  • Request for app permissions to get the permission for [Shipping information].
• Get the user consent for [Shipping information] through Kakao Login.
  • Refer to User consent for detailed operation of the APIs when the user did not consent to [Shipping information],

When using Kakao SDK, request the shipping address as below.

1. Request Select shipping address API to get the shipping address ID.
2. Request Retrieve shipping address API with the shipping address ID to get the shipping address.

Refer to the sequence diagram below.

1. The user selects a button to select a shipping address on the service page.
2. The service request Select shipping address API.
3. The shipping address picker is prompted.
4. The user selects a shipping address according to the information of the Kakao account.
   • If there is no shipping address of the Kakao account, the user can register a new shipping address with the consent.
   • If there are shipping addresses of the Kakao account, the user can select one of them.
5. The service gets the shipping address ID of the selected shipping address from the response of Select shipping address API.
6. The service request Retrieve shipping address API with the shipping address ID.
7. The service gets the selected shipping address from the response of Retrieve shipping address API.
8. The service displays the user's shipping address on the service page.

In the process, errors may occur depending on the user's Kakao account status. Refer to Troubleshooting for more details.

Note: shipping address list

To get the list of all shipping addresses of the user, request Retrieve shipping address API without a shipping address ID. In this case, the service must implement the list UI to allow users to select a shipping address.

OpenID Connect

OpenID Connect (OIDC) is an authentication layer built on top of the authorization protocol, the OAuth 2.0. For detailed specifications, refer to OpenID Connect Core 1.0.

You can decide which protocol to apply when integrating Kakao Login in your service, considering the differences between OAuth and OpenID Connect.

OIDC authentication flow

As OIDC works on top of OAuth, the login process with OIDC protocol is the same as the OAuth authorization process.

Here is the sequence diagram of the OIDC process. If you request tokens with OIDC enabled, you will get an ID Token along with an access token and a refresh token when you request tokens.

ID Token

The ID token is a security token in JSON Web Token (JWT) format encrypted with the RS256 algorithm. The ID token contains the claims consisting of Header, Payload, and Signature separated by period(.) and is encoded using Base64 algorithm. Because the ID token contains identity information for a user, you can use the issued ID token to retain a session in your service. You can also implement the Single Sign-On (SSO) functionality in your service. For detailed specifications, refer to JSON Web Token (RFC7519).

You can also decode the ID token by calling the Getting ID token information API, which is allowed to use only for debugging.

How to integrate OIDC

The way to integrate OIDC is basically the same as OAuth, except for OIDC activation and using the scope parameter.

Features

• Refer to Scope of support to know whether each Kakao SDK supports each feature.