Utilize

This document provides additional information related to Kakao Login.

The API and field names in this document are based on the REST API. Since names may different across development platforms, see the platforms documentation.

Login

This section provides additional information on login offered by the Kakao API platform.

Kakao Account Easy Login

When requesting Kakao Login, displays an account selection screen if easy login information for a Kakao Account is stored in the browser. For platform support and development documentation, see Supported features.

Usage guide

1. The service requests the Get authorization code API with the prompt parameter set to select_account.
2. If the user previously selected [Save Login Information] on the Kakao Account login page using the browser, the account selection screen is displayed.
3. The user can log in by selecting the desired account without entering an ID or password.

Auto-login from Kakao Talk

This feature enables users who signed up via Kakao Login to be redirected to a logged-in page automatically when accessing the service page through the Kakao Talk in-app browser. For platform support and development documentation, see Supported features.

Usage guide

1. The service checks whether the UserAgent value of the user's browser contains KAKAOTALK to determine if the user is using the Kakao Talk in-app browser. Auto-login in Kakao Talk is only available when the user's browser is the Kakao Talk in-app browser.
2. If the user's browser is the Kakao Talk in-app browser, the service requests the Get authorization code API with the prompt parameter set to none.
3. The service must verify the service member status based on the response from the Get authorization code API and handle the flow using one of the methods below.
   • Authorization code response: A service member who signed up via Kakao Login, the service requests the Get token API using the received authorization code to complete the login process and displays the logged-in service page.
   • consent_required error response: Not a service member. The service must displays the service page in a logged-out state.

Note: Kakao Talk in-app browser

The Kakao Talk in-app browser is an embedded browser that opens within Kakao Talk and includes the KAKAOTALK string in the UserAgent value. (Info: User agent, User agent header)

Reauthentication login

This feature displays the Kakao Account login request page, requiring users to log in with their Kakao Account, regardless of their current login status with the service.

When the service requests the Get authorization code API with the prompt parameter set to login, the user must go through the authentication and login process again. For platform support and development documentation, see Supported features.

Login after Kakao Account signup

This feature first prompts the user to sign up for a Kakao Account and then requests Kakao Login upon completing the signup process.

If the service sets the prompt parameter value to create when making a request to the Request authorization code API, the user is first presented with the Kakao account sign-up page. After completing the sign-up, the user is directed to the consent screen to proceed with Kakao login. For platform support and development documentation, see Supported features.

Request additional consent

This feature enables a service to request authorization for the consent items that the user has not previously agreed to at any desired time. For platform support and development documentation, see Supported features.

See the step-by-step guide below.

{
    "id": "${USER_ID}",
    "scopes": [ // Compare with the required consent items list
        {
            "id": "profile",
            ...
            "agreed": true, // Check user consent status
            ...
        },
        ...
    ]
}

HTTP/1.1 403 Forbidden
{
    "msg": "insufficient scopes.",
    "code": -402,
    "api_type": "TALK_MEMO_DEFAULT_SEND",
    "required_scopes": [
        "talk_message" // User consent required for the scope
    ],
    "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" // Information on the scopes the user has agreed to
}

Scope parameters of the Get authorization code API

The Get authorization code API for Kakao Login applies the scope IDs set in the app as default values for the scope parameter when it is not included in the request.

However, the Request additional consent API (the Get authorization code API with the scope parameter) does not support default values, so you must specify the consent item IDs. In this case, for apps with OpenID Connect enabled, the scope parameter must include openid to receive an ID token when calling the Get token API.

See the table below for Kakao Login behavior based on whether OpenID Connect is enabled and whether the scope parameter is included.

Provide login hint

This feature enables an existing user to log in more easily by automatically entering the provided ID value on the Kakao Account login page when Kakao Login.

If the service specifies the login_hint parameter value in the Get authorization code API as the value to be automatically entered in the ID field, the Kakao Account login page will pre-fill the field with the provided value. This feature works only when displaying the Kakao Account login page to users who are not logged in. For platform support and development documentation, see Supported Features.

Simple Signup

This is an additional feature that requests service Terms and consent items together on the Kakao Login consent Screen.

If Simple Signup is enabled for the service, users can agree to the consent items and service terms in a single step on the Kakao Login consent screen, and sign up without entering additional information.

For configuration instructions, see Set up. For platform-specific usage, see Kakao Sync Concepts and Developer documentation.

Get consent to desired service terms

This feature enables requesting authorization from the user for the service terms registered in the service app. The service can use this feature when a user must consent to a specific service terms. For platform support and development documentation, see Supported Features.

Usage guide

1. The service registers the required service terms by referring to Add a new service terms. The service must comply with service terms management.
2. The service requests the Get authorization code API with service_terms parameter, which contatins service terms tags to obtain user consent. At least one service term must be set as [Required consent].
3. The user consents to the specified service terms on the consent screen and completes the signup process.

Get ID token of OIDC

This feature issues an ID token so that the service can use it instead of a login session.

Services that have enabled OpenID Connect can obtain an ID token through a request to the Get token API without any additional parameters. It is recommended to use the nonce parameter to prevent ID tokenreplay attacks. (Note: Parameters for security)

For configuration, see Prerequisites.

Link

This section provides additional information on link, provided by the Kakao API platform.

Manage connected services

The Kakao API platform provides a feature for users to check linked app information, unlink, and revoke consent for [Optional consent] consent items. Users can access the Manage connected services feature through the below paths.

• Kakao Talk: [More] > [Settings] > [Kakao Account] > [Manage connected services]
• [Kakao Account page] > [Account Settings] > [Manage connected services] (Note: Kakao Account page)

Manual signup

This feature enables a service that has disabled the auto-link function to manually link a user to the app at a desired time. For the details, see Advanced: Manual signup.

A service using Manual signup must ensure that the user's service signup status matches the app link status and manage the link status using the Manual signup and Unlink APIs. Unless necessary, it is recommended to use the default auto-link setting.

Note: When Manual signup is required

• When a user completes Kakao Login but does not immediately complete service signup.
  • Additional signup steps such as information entry or authentication are required.
  • Service signup is approved periodically.
• When the service needs to synchronize the service signup status and the app link status in Kakao Developers.
  • The service exclusively uses Kakao Login as the user authentication method.
• Other cases where the service needs to directly manage the user's app link status.

Usage guide

1. You can check whether automatic linking is enabled in [My Application] > [Kakao Login] > [Auto-link with an app when logging in].
   • Not displayed: Indicates that the app uses automatic linking. To use the manual linking feature, request permission via DevTalk.
   • Displayed: You can configure whether to enable automatic linking.
2. Set [Auto-link with an app when logging in] to Disabled, then request the Advanced: Manual signup API when linking is required.

Logout

This section provides additional information on logout in the Kakao API platform.

Logout of service and Kakao Account

This feature provides a screen where users can choose whether to log out only from the service or log out from both the service and their Kakao Account when logout. For configuration, see Set Logout Redirect URI. For platform support and development documentation, see Supported features.

Usage guide

1. When the service requests the Logout of service and Kakao Account, the user is redirected to the logout selection page.
2. The user selects one of the following options: [Logout from this service only] or [Logout of service and Kakao Account]. The actions for each selection are described below.
   • [Logout from this service only]: Redirects the user to the logout redirect URI registered in the app.
   • [Logout of service and Kakao Account]: Before redirection, Terminates the user's Kakao Account login session if exists. If no session exists, the user is immediately redirected to the logout redirect URI registered in the app information.

Differences by logout method

Consent items

Consent items corresponds to user information requiring consent or features requiring access permissions on the Kakao API platform. The service can request authorization from the user through consent items.

The Kakao API platform configures the consent screen based on the consent items set by the service, requests authorization from the user during login, and provides the resources consented by the user to the service. If a service does not have a member system or does not utilize user information, it is not required to set consent items. If no consent items are set for an app, the Kakao Login consent screen only shows the linking information between the service app and the user's account.

For the details on setting consent items in the service app, see Prerequisites.

Consent levels

This setting allows you to adjust the consent level for requesting user authorization for consent items. See the table below for more details.

Personal information consent items

This is a list of consent items that must be set in the app to receive specific user information requiring consent from the Kakao API platform. For the details on setting consent items in the service app, see Prerequisites.

* Profile information (Nickname/Profile image): Deprecated. Now provided separately as [Nickname] and [Profile image]. For the details, see the notice.

Access permission consent items

This is a list of consent items that must be configured in the app to use specific features requiring access permissions on the Kakao API platform.

Permission to set consent levels

To set the consent level as [Required consent], [Optional consent], or [Consent during use], obtain the necessary permission through Request for app permissions. Some consent items are available only for the service that adapted Kakao Sync. For the details on Kakao Sync and the adoption process, see Kakao Sync Getting started.

Note: Providing restricted features

The consent items are subject to the below restrictions unless permission is granted.

• Available only to the app’s team members.
• Subject to quota limits.

A service applying consent items with restricted features can be provided to all users by following the procedure below.

1. Set the restricted consent level and implement the service for team members.
2. Request permission for the relevant consent item on the Kakao API platform.
3. After obtaining permission, set the consent item with the desired consent level in the service app.
4. Provide the service to all users.

Note: Test app permission

This is the permission to set consent levels provided for test apps (Test applications).

A test app is used to develop new features or updates without affecting the app in actual service. The test app permission can be utilized before submitting a review request. For the details, see Test app.

User consent

The Kakao API platform does not provide resources associated with consent items that the user has not agreed to, and returns an error response. In case of an error, call the Request additional consent API to obtain user consent. For resources essential to the service, set the corresponding Consent item as [Required consent] and enable Provision after collecting information through Kakao Account, or implement exception handling for cases where the resource is unavailable.

Provision after collecting information through Kakao Account

This feature enables the provision after collecting user information requiring consent that is not available in the Kakao Account, after obtaining third-party consent from the user on the consent screen. For setup instructions, see Prerequisites.

Behavior by consent level

• [Required consent]
  • Information is collected and provided during the Kakao Login process.
• [Optional consent], [Consent during use]
  • Information is collected and provided when the service requests Request additional consent API, but it cannot be collected or provided during the Kakao Login process.

Items that cannot be configured

• [Kakao Account (Phone number)]
  • This information is linked to the phone number registered in Kakao Talk. Therefore, if the user does not use Kakao Talk, it cannot be collected.
• [Profile (Nickname/Profile image)], [Nickname], [Profile image]
  • Always provided as a required input item when logging in with a Kakao Account.

Revoke consent

Users can revoke their consent for optional consent items through the [Account use] menu on the Kakao Account page or the [Settings] > [Kakao Account] > [Manage connected services] menu in Kakao Talk. In this case, the Revoke consent API is called, and the service can also request this API to revoke user consent. (Note: Manage connected services)

For platform support and development documentation, see Supported features.

User information

This section explains about the user information that the Kakao API platform offers to services. The service must directly collect any user information that the Kakao API platform does not provide.

Default provided information

This information provided to services by default without user consent. This information is provided in the response of the Retrieve user information API.

User properties

This feature allows services to store user-specific information on the Kakao API platform using the Store user information API. The service can retrieve user information through the Retrieve user information API. For the setup instructions, see Prerequisites. For platform support and development documentation, see Supported features.

User information requiring consent

Information provided to services that have obtained authorization for the corresponding consent items. For the complete list and the details, see Personal information consent items.

Shipping address

This section provides information on the shipping address, one of the user information requiring consent.

The Kakao API platform provides shipping address information registered in the Kakao Account of a user who has logged in with Kakao. It can be requested via Kakao SDK (JavaScript, Android, iOS, Flutter) or REST API. For platform support and development documentation, see Supported features.

The details for each development platform are as belows.

Usage guide for Shipping address picker with Kakao SDK

When using the Kakao SDK, see the following sequence diagram for the process of requesting a shipping address through the Shipping address picker.

1. The user selects [Select] on the service page.
2. The service calls the Select shipping address API.
3. The Shipping address picker is displayed to the user.
4. Depending on whether the user's Kakao Account has registered shipping addresses, the user selects a shipping address using one of the below methods.
   • If no registered shipping address: The user consents to collect a shipping address, enters a new address, and the newly entered address is automatically selected.
   • If registered shipping addresses exist: The user selects a shipping address to provide to the service.
5. The selected shipping address ID is returned as a response to the Select shipping address API.
6. The service requests the Retrieve shipping address API using the shipping address ID.
7. The detailed shipping address information is returned as a response to the Retrieve shipping address API.
8. The service displays the details of shipping address that the user selects.

For solutions to errors that may occur during above process, see Troubleshooting.

Note: Retrieving all shipping addresses

If a shipping address ID is not specified when requesting a shipping address, the API returns the user's full list of registered shipping addresses. In this case, the service must implement a UI to display all of the received addresses and allow the user to select a shipping address.

Determining whether user consent is required

The Kakao API platform includes a field indicating the availability of user information in API responses when the user consents.

If the response field name for user information is ${FIELD_NAME}, the field indicating availability is named ${FIELD_NAME}_needs_agreement. See the details below for the meaning of each response value.

• true: User information requiring consent.
  • Can be provided after obtaining the user's third-party consent through Request additional consent.
• false: User information not requiring consent.
  • If the ${FIELD_NAME} field exists in the successful API response: The information is already provided.
  • If the ${FIELD_NAME} field does not exist in the successful API response: The information cannot be provided by the Kakao API platform and must be collected separately by the service.
  • If the provision after collecting information through Kakao Account option is not selected for consent items for user information not available in the Kakao Account: When this option is selected, user consent can be obtained and the information can be provided after collection

Example: Additional consent required for the email consent item

HTTP/1.1 200 OK
{
    ...
    "kakao_account": {
        ...
        "email_needs_agreement": true    // User consent required for the email consent item
        ...
    }
}

OpenID Connect

Kakao Login supports OpenID Connect (OIDC), a standard authentication protocol based on OAuth 2.0. By applying OIDC to a service, user login can be handled more securely. For setup instructions, see Prerequisites, and for platform support and development documentation, see Supported features.

See the implementation guide below for applying OIDC to Kakao Login.

ID token

An ID token is a JSON Web Token (JWT) that can be used as a login session for a service. The service can utilize the user authentication information contained in the ID token or verify the validity of the ID token. The expiration time of an ID token is the same as that of an access token.

An ID token consists of the below three segments.

ID tokens are generated as a single string by Base64 encoding each of the three sections and concatenating them with a period (.). Therefore, you can separate each section using the period (.) as a delimiter and decode them with Base64 to inspect their contents. For the methods for verifying the payload and signature, see Verify ID token.

Webhook

Unlink webhook

This feature notifies the service server in real-time when a user unlinks from the service through the below methods.

• If a user deletes their Kakao Account.
• If a user selects [Disconnect] on the Manage connected services page.
• If a user requests to unlink from the service through Kakao Customer Service.
• If the Kakao API platform unlinks a user who has not completed the service registration.

If the service directly requests the Unlink API, the webhook is not sent.

Usage guide

1. The user requests to unlink from the service.
2. The Kakao API platform processes the unlink request and then sends an unlink webhook to the service.
3. The service must respond to the Kakao API platform server after taking necessary actions according to its privacy policy, including user information deletion when a user deletes the account and account deletion.

For configuration instructions, see Prerequisites, and for development documentation, see Unlink webhook.

Account status change webhook

This feature notifies the service server in real-time when a user's Kakao Account status changes. The below is key changes provided via webhook.

• Profile information updates (email, phone number)
• App link or unlink
• Password change
• Account deactivation

With webhooks, services can immediately detect user changes and take security measures such as session termination or reauthentication requests, or keep user information up to date.

Usage guide

1. A user's account status changes.
2. Kakao sends a Security event token (SET) containing event information to the service's webhook URL.
3. The service validates the SET information received at the webhook URL. The service must respond with either success or failure.
4. The service takes the necessary actions based on the Event type.

For the details on implementation, see the developer documentation.

Security

This section explains detailed information on the security features of Kakao Login offered by the Kakao API platform.

Client secret code

This security feature ensures that requests to the Get token API and Refresh token API via the REST API method succeed only when a pre-issued Client secret code is included in the client_secret parameter. For the configuration, see Prerequisites.

It is recommended to update the Client secret code every two years or less. If the Client secret code is missing or incorrect, a KOE010 error occurs.

Parameter for security

Kakao Login provides the state and nonce parameters for the Get authorization code API to enhance security in accordance with the OAuth 2.0 and OpenID Connect standards. It is recommended to use these parameters to ensure a secure login process.

The state parameter is used to protect the Kakao Login request from Cross-Site Request Forgery (CSRF) attacks. This parameter must be unique and remain consistent from the start to the completion of the login process.

The nonce parameter, supported in OpenID Connect, helps prevent ID token replay attacks. The nonce value sent in the Kakao Login request is included in the ID token, allowing the service to check if it matches and prevent replay attacks.