페이지 이동경로
  • Docs>
  • Kakao Login>
  • Understand concepts

Kakao Login

Understand 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 since Kakao does not access or modify service data, such as saving or deleting user information.

Kakao Login use cases

Here are the functions required for Kakao Login:

Name Description
Login Identifies users through their Kakao Accounts and gets permission to call Kakao APIs with the user information. You can collect user data, instead of requiring users to input their service IDs and passwords for identification. Through the Kakao Login API, a user can link to your app, and tokens are issued. The tokens are used to identify a user and make an API call with the user information on the Kakao platform.
Link Links an app with a Kakao Account so that you can call the Kakao APIs from the app.
Logout Expires the access and refresh token issued through the login process to have a user log out. When a user requests to log out or a service requests to make a specific user log out, the Logout API is invoked, and then the tokens expire.
Even after the logout, a user can log in and link to your app again using the same Kakao Account. However, make sure that the previous user information stored on the app cannot be recovered.
Unlink Unlinks your app with a user's Kakao Account. After a user unlinks from your app, you cannot make user-related API calls with the user's information in your app anymore, and all of the user data is completely deleted from the Kakao platform.
Even after the unlink, a user can log in and link to an app again using the same Kakao Account. However, make sure that the previous user information stored on the app cannot be recovered.
Token Verifies if you are authorized to make API calls by using the access token that is issued during the Login process.

Login

When a user logins with Kakao, Kakao authorizes a third-party application 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.

Login process Step 1. Kakao Login
  1. Once a user requests to log in with Kakao, Kakao requests user's credential and asks users' consent according to a user envrionment or choice. See Authorization methods according to user environments for more details.
    - Login with Kakao Talk: As Kakao Talk is launched, the user is logged in with the Kakao Account information linked to Kakao Talk.
    - Login with Kakao Account: In a web environment or on a device where Kakao Talk is not installed, the user is asked to log in with the user’s Kakao Account ID and password.
  2. Once the user logs in and gives permission for your app to access the user's data, the Kakao authorization server validates the user’s credentials and issues an authorization code. The user is redirected back to your app with the authorization code via redirect_uri.
  3. Your app requests to exchange the issued authorization code for an access token and a refresh token.
  4. The Kakao authorization server issues an access token and a refresh token based on the authorization code, and provides authentication. See Token information to learn more about the access and refresh token.

If a user's Kakao Account has successfully been linked with your app, the tokens are issued. Then, you can retrieve information of the user who is currently logged in through the Retrieving user information API to use the user data for your service.

If a user fails to log in, the first thing you need to do is checking out its response. The Kakao server sends the response code, including the reason for the failure. In this case, check its cause and fix the problem by referring to Troubleshooting.

Step 2. Check signup status
  1. The service server requests to retrieve user information with the issued access token.
  2. The Kakao API server validates the access token passed in the request. If the token is valid, respond to the request sent from the service server.
  3. The service server checks if the user has been signed up for the service by using the provided user information, and handles the user differently depending on the user's signup status.
    • For a user who has already signed up: Skip to Step 3. Log into service.
    • For a user who has not signed up: Store the user information provided by Kakao in the service database to complete signup.
Step 3. Log into service
  1. If the user has been signed up for the service, the service server creates a login session.
    NOTE: If you use OpenID Connect, you can use the issued ID token as a service session.
  2. The service client completes the login and shows the user to the service page in logged-in status.

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.

Token Type Role Valid period
Access token Used to give your app permission to request data and to authenticate API calls. Android, iOS: 12 hours
JavaScript: 2 hours
REST API: 6 hours

NOTE: Has relatively short validity period due to security reasons.
Refresh token Used to gain a new access token and refresh token without an additional verification process for a certain period. 2 months

NOTE: Possible to refresh the tokens only a month before the access token expires.
ID token Used to authenticate users. See ID Token.

IMPORTANT: Only returned if you integrate OpenID Connect, and required to verify in the client-side.
Android, iOS: 12 hours
JavaScript: 2 hours
REST API: 6 hours

NOTE: Has same validity period as the access token.

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.

Type Environment Description
Android SDK Android mobile device The Kakao Account information linked with Kakao Talk is used.
If Kakao Talk has not been installed on a user's device, the user needs to input Kakao Account information on a web page.
iOS SDK iOS mobile device The Kakao Account information linked with Kakao Talk is used.
If Kakao Talk has not been installed on a user's device, the user needs to input Kakao Account information on a web page.
JavaScript SDK PC or mobile web browser On mobile: The Kakao Account information linked with Kakao Talk is used.
On PC: Users need to input Kakao Account information on a web page.
REST API PC or mobile web browser On mobile: Users need to input Kakao Account information on a web page. When a user selects [Login with Kakao Talk] on a web page, the Kakao Account information linked to Kakao Talk is used.*
On PC: Users need to input Kakao Account information on a web page.

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

Process of Login with Kakao Talk Process of Login with Kakao Account
Basic verification method of Kakao Login

The Kakao SDK provides the easiest verification method for users as a default, but also allows you to select a different verification method. Refer to each development guide according to the platform that you are developing with.

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.

OAtuh 2.0 OpenID Connect
Definition Web authorization protocol Authentication layer on top of OAuth 2.0
Purpose To verify what resource a user has access to,
To grant access or usage permission from users
To verify who a user is
Token Access token, Refresh token Access token, Refresh token,
ID Token
Use case API authorization Maintaining session
Single Sign-On (SSO) functionality
OIDC authentication flow

Since OIDC is 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.

Process of OIDC authentication

How to integrate OIDC

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

Step 1. Enable OIDC function

Go to [My Application] > [Kakao Login], and then activate the OpenID Connect.

Step 2. Check Discovery document

When you send a request to /.well-known endpoint/openid-configuration, you can access the Discovery document and retrieve the metadata that you may need while implementing OIDC.

With the discovery document, you can retrieve:

  • URLs of the endpoints for authorization, tokens, user information and JSON web key.
  • Configuration of Kakao authorization server for OIDC.

To see the response fields included in the Discovery document, see REST API > Retrieve Discovery document.

Step 3. Implement Kakao Login

Implement Kakao Login by referring to the development guide. When you call the Login API, you will get an ID token. For a REST API, refer to Advanced: Login with Open ID Connect.

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. Since 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).

Segment Description
Header Encryption information that contains:
- alg: Encryption algorithm applied to ID token. Fixed as RS256.
- typ: Type of ID token. Fixed as JWT (JSON Web Token).
- kid: Cryptographic key ID.
Payload User authentication information that contains:
- iss: Issuer Identifier. Fixed as https://kauth.kakao.com.
- aud: App key of the app which the ID token is issued for.
- sub: Service user ID.
- iat: Time when the JWT was issued
- auth_time: Time when a user was authenticated.
- exp: Validity period of ID token in seconds, which is the same as that of access token.
- nonce: Random string passed in the request of the Getting authorization code API.
Signature Signed value with a public key provided by the Kakao authorization server.

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

IMPORTANT

If you call the requesting additional consent API, you must add 'openid' to 'scope', the required parameter. If not, OAuth is applied even though OIDC is enabled, which means that you cannot get an ID token. If you don't pass the 'scope' parameter when requesting additional consent, the Login API is called with the scopes as specified in [My Application] > [Consent Items].

Step 4. Verify ID token

When your service obtains an ID token from Kakao, you need to check the integrity on your service server by verifying the issued ID token as follows:

  1. Separate the ID token into Header, Payload, and Signature by period(.).
  2. Decode the payload from Base64 format.
  3. To verify that the ID token is issued from Kakao authorization server (kauth), check if the value of iss in the JWT payload is https://kauth.kakao.com.
  4. Check if the value of aud in the JWT payload is your app key. The app key type may differ depending on the platform you use.
  5. To verify that the ID token's expiration time has not passed, check if the value of exp is greater than UNIX timestamp of the current time.
  6. (Optional) If you pass nonce in your request to prevent replay attacks, check if the value of nonce in the JWT payload matches the nonce value passed in your request.
  7. Check if the issuer has properly signed the ID token with the public key by verifying cryptographic signature.
Verifying Cryptographic signature

The JSON Web Key Set (JWKS) is a set of keys containing the public keys used to verify any JSON Web Token (JWT) issued by the authorization server and signed using the RS256 signing algorithm.

  1. To find out a public key, call the Getting public key.
  2. Check kid passed in the response.
    IMPORTANT: Ensure that the public key may change periodically or when some issues occur. Thus, you must make use the public keys by caching them in your service periodically.
  3. Verify ID token with kid by using the official libraries:
    - OpenID Foundation
    - jwt.io

Since the cryptographic signature checking process is complicated, we strongly recommend using the official libraries above. However, if you want to decrypt and verify the ID token internally in your service instead of using libraries, refer to 5.2. Message Decryption in JSON Web Encryption (RFC 7516).

Step 5. Retrieve User information

If your service needs to retrieve user information about the user authenticated through OIDC and use the claims for data mapping, call the Retrieving user information for OIDC. This API complies with the Standard Claims, and only provides the basic user information unlike the Retrieving user information.

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.

Configured consent screen

The scope set as 'Consent during use' is not displayed on the Consent screen prompted when a user attempts to log in. If you request additional consent for the scope, the consent screen with the scope added as a [Required consent] is prompted at the moment when the user information is required.

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 [General Settings] > [Privacy] > [Kakao Account] > [Manage Connected Services] on the Kakao Talk application or in [Use Your Account] > [Manage Connected Services] on the Kakao Account page.

Consent screen

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:

IMPORTANT

The contents of the API response can be added or deprecated. For the case that properties are added, you need to implement exception handling. For change properties, we will notify you through DevTalk so that you can take action.

User information 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 sings 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.

Name Description
id Service user ID.
kakao_account Kakao Account information.
connected_at The time when the user is linked with a service.
synched_at The time when the user is logged in through Kakao Sync Simple Signup.


Providing conditions: Only passed for Kakao Sync service users. In this case, its value is the same as connected_at.
properties Additional user information saved on the Kakao platform to use it later.
Refer to Prerequisites > User properties.

User information 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.

User information Description Required user consent
Profile Profile information of Kakao Account.

Include:
- Nickname
- Profile image URL
- Thumbnail image URL
- Whether the default image is used for profile image
- Whether consent to profile is required
NOTE: From June 25, 2021, you can request consent to the nickname and the profile image of the profile information separately. Refer to Notice for more details.
Profile Info(nickname/profile image)
or
Nickname
Profile image
Email Representative email of Kakao Account.
Email may not be collected in a user's Kakao Account. In this case, use the Provision after collecting information option or collect it in your service internally.
A user's Kakao Account email may not be verified. If your service needs to use only verified emails, proceed the verification process for the users who do not have unverified emails.

Include:
- Representative email of Kakao Account
- Verification status of email
- Validation status of email
- Whether consent to email is required
IMPORTANT: Kakao Account email may change as a user requests. For this reason, we recommend not to use email as an ID or to identify users by emails.
Email
Permission
Name Name of Kakao Account.
If a name is not registered in a Kakao Account, use the Provision after collecting information option.
Name
Permission
Age Range Age range of Kakao Account based on Korean age.

Include:
- Age range
- Whether consent to age range is required
Age range
Permission
Birthday Birthday of Kakao Account.

Include:
- Birthday
- Birthday type
- Whether consent to birthday is required
Birthday registered in Kakao Account.
Permission
Birth year Birth year of Kakao Account.

Include:
- Birth year
- Whether consent to birth year is required
Birth Year registered in Kakao Account.
Permission
Gender Gender of Kakao Account.

Include:
- Gender
- Whether consent to gender is required
Gender
Permission
Phone number Phone number of Kakao Account.

Include:
- Phone number
- Whether consent to phone number is required
IMPORTANT: The Provision after collecting information is not applicable for Phone number.
Phone number
Permission
CI(Connecting Information) Cryptographic user identification value.
CI can be used only to check if the same user has already been registered in the membership database.

Include:
- Connecting InformationThe time when Certificate Authority issues CI
- Whether consent to CI for a reference is required
IMPORTANT: Use CI provided by Kakao only to compare with CI collected by a service. You cannot use CI for user authentication because Kakao does not have a role as Certificate Authority.
CI(Connecting Information)
Permission
Checklist: Things to do if user information is not passed

If you cannot get a specific user information such as email that you need through the Retrieving user information API, proceed the followings:

1. Check if you enable the consent item for the user information in Consent Items. You must set it to either 'Required consent' or 'Optional consent' to get the user information. If you must obtain consent to a specific user information, use the Provision after collecting information option.

2. Check the {FIELD_NAME}_needs_agreement key, such as email_needs_agreement. If the key value is 'true', request additional consent to obtain consent by prompting the Consent screen.

User information 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.

User information Description Required user consent
Shipping information Shipping information of Kakao Account. Shipping information
Permission
Kakao Talk profile Profile of Kakao Talk.
This profile is different from Kakao Account profile.

Include:
- Nickname
- Profile image URL
- Thumbnail image URL
Profile Info(nickname/profile image)
Kakao Talk friend information Friend information of Kakao Talk.

IMPORTANT: After permission for the Retrieving list of friends API is granted, you can get a list of friends who meet the condition.
Friends List in Kakao Service(Including profile image, nickname, and favorites)
Permission
Kakao Talk Channel addition status and details Relationship between a Kakao Talk Channel and a user.
If you connect your Biz app to one or more than Kakao Talk Channels in Kakao Business, you can set the required consent item to 'Optional consent' item.
Kakao Talk Channel addition status and details
Kakao Story profile Profile of Kakao Story.
This profile is different from Kakao Account profile.

Include:
- Nickname
- Profile image URL
- Thumbnail image URL
- Background image
Profile Info(nickname/profile image)
Kakao Story Birthday Birthday registered in Kakao Story.

Include:
- Birthday
- Birthday type
Birthday
KakaoStory Profile URL Kakao Story profile URL. KakaoStory profile URL

Logout

The Logout API allows a user to log out of service as the access token and the refresh token, issued through the Kakao Login process, expire. After a user is logged out, you cannot call any Kakao APIs using the user information in the service. Since the Logout API only limits the usage of Kakao APIs, you need to implement the process of logging out of the service internally.

The logout proceeds differently depending on the login status of the Kakao Account as follows:

  • If a user is logged in with the Kakao Account on multiple devices, the logout only proceeds on the device where the user requests to log out. On the rest devices, the user stays logged in.
  • If a user is logged in to several services with the Kakao Account on a web browser, the user is logged out of a specific service only in which the user clicks [Logout]. On the rest services logged in with the Kakao Account on the same web browser, the user stays logged in.

If you want to log out of both Kakao Account and service when clicking [Logout], you can use the add-on feature, 'Logout of service and Kakao Account'. Then, when a user click [Logout], the user is redirected to the bridge page asking whether to log out of the service only or log out of Kakao Account together with the service. In the basic logout process, the access and refresh tokens expire only. However, in the 'Logout of service and Kakao Account' process, both of the Kakao Account session and the service session expire.

Screenshot of logout of service and Kakao Account

To use the 'Logout of service and Kakao Account' feature, set Logout Redirect URI that a user is redirected to when clicking [Logout], and expire the service session in the service server.

The logout flow proceeds as follows:

  • When a user clicks [Logout], the user is redirected to a bridge page.
  • The user selects whether to 'log out of the service only(A)' or 'log out of Kakao Account together with the service(B)'.
  • If (A) is selected, the user is redirected to the URI set as Logout Redirect URI in [My Application] > [Kakao Login] > [Logout Redirect URI].
  • If (B) is selected, the logout proceeds differently depending on the Kakao Account's login status.
    • If the Kakao Accout session is retained, Kakao ends the Kakao Account session and redirects the user to the set Logout Redirect URI.
    • If the Kakao Accout session is not retained, the user is redirected to the Logout Redirect URI.

You can implement the 'logout of service and Kakao Account' feature using a REST API. See the development document for REST API for more details.

Link

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

Once a user agrees to provide personal information and Terms of Service on the Consent screen when attempting to log in for the first time, Kakao issues tokens and gives permission to call Kakao APIs. Only when a user's Kakao Account is linked with your service, you can call Kakao's token-based APIs, and the user can also use the functions of the Kakao APIs in your service. When a user logs in to a service with a Kakao Account, the user's account is automatically linked to the service by the Kakao platform. Thus, you do not need to request an extra API to link.

Link is an essential term on the Kakao platform in terms of the connection among Kakao, service, and users.

Link your service with Kakao platform

Your service is linked to the Kakao platform through an application (hereinafter referred to as 'app'). The Kakao platform provides APIs based on each app's information and permission specified on the Kakao platform. Thus, if you don't register an app on the Kakao platform, you cannot use Kakao APIs. You can register your service information such as service name and company name when creating app. Also, you can switch to a Biz app by registering your business registration number and connect to your Kakao Talk Channel.

Link your service with a user

From a user's point of view, the Link refers to a connection between the user's Kakao Account and a service app on the Kakao platform. If a user logs in to a service with the Kakao Account, the account is linked with the service app. Users can create a Kakao Account through the Kakao services such as Kakao Talk.

A user can have one or more Kakao Accounts, and a Kakao Account can be linked with several service apps. A service app also can be linked with several Kakao Accounts, which means several users can use a service at once.

Linking vs. Creating an account

While creating an account is a process of registering a user as a member in the service server's membership database, linking account is a process of registering the user in the Kakao Developers app to permit to use the Kakao platform.

If a user creates a new account with Kakao Account in your service, the user information of Kakao Account needs to be registered into your service server's membership database. Ensure that the signup is not completed if without registering in the service database.

On the other hand, the linking does not affect the membership database in the service server since Kakao cannot access the service data. Only after the user is linked with the service app and the service registers the user in the service server's membership database, a new account is created.

Concept of link

Unlink

As opposed to the concept of Link, the Unlink disconnects the connection between a service app and a Kakao Account. If a user unlinks from your app, you cannot make API calls with the user information.

If a user requests to unlink on Manage Connected Services or through Kakao Customer service, or requests to delete the user's account in a service, Kakao unlinks the user account from your service app and makes the service not use the user information afterward.

To deal with the request, you should unlink their Kakao Accounts from your service by calling the Unlink API. Also, according to the Kakao Developer's Terms of Service and Privacy Policy, you should handle the Kakao Account information that users have provided to use your service.

IMPORTANT: Unlink for users who have not completed a signup

Starting December 28, 2020, the users who have not completed a sign up for third-party services will have their accounts set to Unlink. This will be processed every day. If users do not complete sign up and their accounts will be changed to the Unlink state. In this case, you can get an unlink callback. Refer to Notice for more details.

Unlink on Manage Connected Services

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

How to unlink on Kakao Account page and Kakao Talk

The button name to unlink may differ depending on whether to use the unlink callback. See Set unlink callback.

Unlinking vs. Deleting an account

If a user deletes the account, the user information is deleted from the membership database of your service server. On the other hand, unlinking an account does not affect the user information in the service server.

Therefore, you, as a service provider, must process user information after the unlink. For example, if a user who agreed to provide personal information to use your service requests to withdraw consent or unlink from your service, you must delete the user's personal information or the user's account from the service server's database. If you want to get notified who unlinks from your service, you can use the unlink callback function.

Concept of unlink
IMPORTANT

If your service provides iOS apps, you must provide account deletion within your app along with account creation according to the App Store Review Guidelines. Likewise, if you integrate Kakao Login into your service, you must also provide a function to unlink from your app since users are linked to your app when they log in with Kakao. This applies to all apps submitted after January 31, 2022.

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.

IMPORTANT: What to collect internally

If a user refuses to provide their user information, Kakao cannot collect and provide it regardless of using the Requesting additional consent API. In this case, the user information needs to be collected internally. Terms of Service is not applicable for this API. If it is required to add a Terms of Service in the middle of operating your service, you need to obtain additional consent through an internal page.

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:

Whether user is linked to app Whether to pass scope in request How API works User experience
X X Login API is invoked. Consent screen asking permission for the scopes specified in [My Application] > [Consent Items] is prompted when a user attempts to log in.
X O* Login API is invoked. Consent screen asking permission for the scopes as specified through the scope parameter in the request when a user attempts to log in.
O X Login API is invoked. Consent screen does not appear.
Tokens are issued for the scopes specified in [My Application] > [Consent Items].
O O* Requesting additional consent API is invoked for the scope passed through the scope parameter in the request. Consent screen asking for additional consent to the specified through scope is presented when a user performs an action that requires the scope.

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 since the OAuth protocol is applied.

Best practice

Step 1. Check required consent item

There are two main cases when your service requires additional user consent during use of the service:

  • When your service requires additional user information to allow users to use your service.
  • When your service requires consent for a specific scope to call a Kakao API.

If you need to obtain user consent for additional user information, you can call the Retrieving consent details API first to check what scopes a user has already consented.

You can also check it by calling the Retrieving user information API. When you request this API, only the scopes that a user has consented are returned. In this case, you can check the value of ${FIELD_NAME}_needs_agreement to figure out if the scope requires consent. If the user consents to the scope and the user information of the scope is available to provide, the value of scope is returned to true. For more information, refer to needs_agreement.

The following sample snippet is the response of the Retrieving user information API when the user has not agreed to provide Email.

Sample: If user has not agreed to provide Email

{
  "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
  }
}

The response above does not include Email information since the user has not agreed to the Email scope. However, if the value of email_needs_agreement is true, you can get email information if the user agrees. To use the user's Email information in your service, you must request additional consent to Email.

If the Kakao API request fails due to insufficient scopes, you can figure out which API (api_type) requires consent to which scopes (required_scope) by checking the error response. You can also see allowed_scopes to check the scopes that the user has already agreed to. Only after you obtain consent by requesting additional consent to the scope of required_scope, you can use the corresponding API.

Name Description
required_scopes Scopes that a user needs to consent to use the API
allowed_scopes Scopes that a user has consented

The following sample snippet is the response of the Kakao Talk messaging API when the user has not agreed to the required consent item.

Sample: Fail due to no permission to send Kakao Talk message
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"
  ]
}

required_scopes in the response above indicates that you need to obtain consent to talk_message from the user. Only after requesting additional consent to talk_message, you can call the API.

Step 2. Request additional consent

Request additional consent to the required scope for the corresponding API. For the scope key, check 'Scope ID' in the [My Applications]> [Kakao Login] > [Consent items] or see Manage consent item.

To see how to implement, refer to the following development documentation:

Step 3. Reissue token and check result

When you request additional consent, the user may not accept your request by clicking [Cancel]. For this case, you need to check if the user has granted the consent request.

If the user agrees to the required consent item, the response of the Requesting additional consent API is the same as the Getting authorization code API. In this case, you need to get new tokens using the newly issued authorization token by requesting the Getting tokens API.

After that, check the response of the Getting tokens API, and see if the scope you requested additionally is included in scope. If included, you can get the user information of the scope by requesting the Retrieving user information API.

Sample: Response of the Getting tokens API
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":25184000,
    "scope":"account_email profile"     // Scope user has agreed to
}

You can figure out which scopes are required to obtain consent additionally to use a specific API through scope in the response of the Getting tokens API. You can also check if the API request is succeeded. If the user has disagreed or an error occurs, request additional consent or disable the service's function for the user. Allow a user to use your service only when the user has agreed to the required scope.

Scope of support

API Android SDK iOS SDK JavaScript SDK Flutter SDK REST API
Login
Logout
Link
Unlink
Retrieving token information
Refreshing tokens
Retrieving user information
Storing user information
Requesting additional consent
Retrieving user list
Retrieving multiple user information
Retrieving consent details
Revoking consent
OIDC: Getting public key
OIDC: Retrieving Discovery document
OIDC: Retrieving user information
OIDC: Getting ID token information
Manual signup

To implement Kakao Login using a REST API, the Getting authorization code and the Getting tokens APIs are required. the Retrieving user list API is only supported for REST API.