This document describes how to integrate Kakao Login APIs into your service with the Kakao SDK for Flutter.
To learn about each API in detail, refer to Concepts.
For a Kakao Login button, you can download the resources provided by Kakao or customize buttons according to your service user interface by referring to the Design Guide.
To use the features of Kakao Login, you need to add kakao_flutter_sdk_auth
and kakao_flutter_sdk_user
modules in pubspec.yaml by referring to Install SDK.
To use the Kakao Login API on the native app service, you must set the Custom URL Scheme. See how to set up a project by device environment below.
Flutter SDK supports two types of implementation methods for Kakao Login.
API | Recommended environment | Implementation method | Description |
---|---|---|---|
Login with Kakao Talk (Recommended) |
Native app service | Default method: Request authorization code and tokens with one API on the service client. |
Launches Kakao Talk to authenticate users. |
Login with Kakao Account | Opens a pop-up page to log in with a Kakao Account on the default browser. | ||
Login with Kakao Talk: Web (Recommended) |
Web service | Redirect method: Request authorization code on the service client, and then request tokens on the service server. Refer to Kakao Login process: Web. |
Launches Kakao Talk to authenticate users. |
Login with Kakao Account: Web | Moves to the page to log in with a Kakao Account from the service page. |
Native app services can not use the redirect method.
The Kakao Account login page may not be properly displayed on the web browser or web view. But when implemented using the Redirect implement method, the Kakao Account login page can be opened from the service page without pop-ups.
Login with Kakao Talk or Login with Kakao Talk: Web is highly recommended for a user environment supporting Kakao Talk. To check if launching Kakao Talk is available, use isKakaoTalkInstalled()
. The results are below.
true
false
For the services that support multiple accounts or user environments that do not support Kakao Talk, Login with Kakao Account or Login with Kakao Account: Web is recommended.
Determine which authentication method to use for the user environment and service flows. Two authentication methods can be used both. Refer to each document.
When using the Login with Kakao Talk: Web or Login with Kakao Account: Web for the redirect method, the service must request tokens from the service server to complete the Kakao Login process. The Kakao Login process using the redirect method is below.
1. Get authorization codeisKakaoTalkInstalled()
to check if launching Kakao Talk is available.true
is returned, use Login with Kakao Talk: Web.false
, use Login with Kakao Account: Web.The service must implement the user's login process to the service. This document provides a guideline to implement the login process.
To use Select shipping address API, set a custom URL scheme in AndroidManifest.xml. Refer to the sample below.
<application>
<activity
android:name="com.kakao.sdk.flutter.AppsHandlerActivity"
android:exported="true">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.DEFAULT" />
<category android:name="android.intent.category.BROWSABLE" />
<!-- Setting for the shipping address picker -->
<data android:scheme="kakao${YOUR_NATIVE_APP_KEY}" />
<data android:host="address" />
</intent-filter>
</activity>
</application>
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
- | Register platforms Activate Kakao Login Manage consent items Advanced: Activate OpenID Connect(Optional) Set Simple Signup(for Kakao Sync) |
Required | Required: Required consent item |
isKakaoTalkInstalled() loginWithKakaoTalk() KakaoException |
Request loginWithKakaoTalk()
in UserApi
. Flutter SDK launches the Kakao Talk application and prompts the Consent screen asking for consent.
Name | Type | Description | Required |
---|---|---|---|
nonce | String |
Parameter to strengthen security. To prevent replay attacks, generate random strings and pass them as an argument. IMPORTANT: Allowed to set only when you integrate Kakao Login with OpenID Connect. |
X |
// Login with Kakao Talk
try {
OAuthToken token = await UserApi.instance.loginWithKakaoTalk();
print('Login succeeds. ${token.accessToken}');
} catch (e) {
print('Login fails. $e')
}
When a user consents, Kakao identifies the user with the user's Kakao Account information linked to Kakao Talk, and then issues tokens. The Flutter SDK provides the issued tokens through the OAuthToken class.
The issued tokens are stored through the TokenManagerProvider
class. The stored tokens are automatically added to the authorization header when calling the token-based APIs.
Name | Type | Description | Required |
---|---|---|---|
accessToken | String |
One of the tokens that authorizes you to call Kakao APIs and identifies users. | O |
expiresAt | DateTime |
Validity period in seconds until the access token expires. | O |
refreshToken | String |
One of the tokens that is used to gain new tokens. IMPORTANT: Not included when using JavaScript app key |
X |
refreshTokenExpiresAt | DateTime |
Validity period in seconds until the refresh token expires. IMPORTANT: Not included when using JavaScript app key |
X |
scope | List<String> |
List of scopes of user information to be retrieved with the issued access token. | X |
idToken | String |
JSON Web Token that contain user's authentication information, encoded using Base64 algorithm. For more details, refer to ID Token. IMPORTANT: Only returned when you integrate Kakao Login with OpenID Connect. If you call the Requesting additional consent API, only returned when openid is added to scope in the request. |
X |
* Deprecated 'accessTokenExpiresAt'. Instead, use 'expiresAt'.
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
- | Register platforms Activate Kakao Login Manage consent items Advanced: Activate OpenID Connect(Optional) Set Simple Signup(for Kakao Sync) |
Required | Required: Required consent item |
loginWithKakaoAccount() KakaoException |
Request loginWithKakaoAccount()
in UserApi
. Flutter SDK opens a pop-up page to log in with a Kakao Account. Users can log in with an ID and password. After login, the Kakao Login consent screen is displayed.
Name | Type | Description | Required |
---|---|---|---|
prompts | [Prompt] |
Used to request reauthentication by selecting whether to present an interactive UI. - .login : Used to request reauthentication by presenting the Kakao Account Login screen to a user even though the default web browser already retains cookies about the user's login information through Kakao Account.- .create : Used to prompt the Kakao Account sign-up page first. The Kakao Login consent screen is displayed after signing up for Kakao Account.- .select_account : Used to prompt the Kakao Account easy login. If Kakao Account login sessions are on the browser, the login page processes login automatically or prompts the account selecting page. The account selecting page is prompted when there are more than two Kakao Account login sessions on the browser. |
X |
loginHint | String |
Used to request with Login hint A value to fill in ID field of the Kakao Account login page. Note: Highly recommend to refer to Login process with login hint Note: Users can login with their email, phone number, and ID of Kakao Mail on the Kakao Account login page. |
X |
serviceTerms | String |
Used to request Get consent to desired service terms API. Tags of desired service terms. You can find tag values in [My Application] > [Simple Signup]. Pass the tag values as a comma-separated string. |
X |
nonce | String |
Parameter to strengthen security. To prevent replay attacks, generate random strings and pass them as an argument. IMPORTANT: Allowed to set only when you integrate Kakao Login with OpenID Connect. |
X |
// Login with Kakao Account
try {
OAuthToken token = await UserApi.instance.loginWithKakaoAccount();
print('Login succeeds. ${token.accessToken}');
} catch (e) {
print('Login fails. $e')
}
When a user consents, Kakao identifies the user through the user's Kakao Account cookie stored on the default web browser and then issues tokens through the OAuthToken class.
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
- | Register platforms Activate Kakao Login Set Redirect URI Manage consent items Advanced: Activate OpenID Connect(Optional) Set Simple Signup(for Kakao Sync) |
Required | Required: Required consent item |
isKakaoTalkInstalled() authorizeWithTalk() KakaoException |
Request authorizeWithTalk()
in AuthCodeClient
. Flutter SDK launches Kakao Talk and displays the Kakao Login consent screen.
When the user agrees to all required consent items and selects [Agree and Continue], the authorization code is passed to the Redirect URI.
To get tokens, request tokens using the authorization code from the service server. Refer to Kakao Login process: Web.
try {
await AuthCodeClient.instance.authorizeWithTalk(
redirectUri: '${REDIRECT_URI}',
);
} catch (error) {
print('Failed to login $error');
}
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
- | Register platforms Activate Kakao Login Set Redirect URI Manage consent items Advanced: Activate OpenID Connect(Optional) Set Simple Signup(for Kakao Sync) |
Required | Required: Required consent item |
isKakaoTalkInstalled() authorizeWithTalk() KakaoException |
Request authorize()
in AuthCodeClient
. Flutter SDK opens the Kakao Account login page from the service page. Users can log in with an ID and password. After login, the Kakao Login consent screen is displayed.
When the user agrees to all required consent items and selects [Agree and Continue], the authorization code is passed to the Redirect URI.
To get tokens, request tokens using the authorization code from the service server. Refer to Kakao Login process: Web.
try {
await AuthCodeClient.instance.authorize(
redirectUri: '${REDIRECT_URI}',
);
} catch (error) {
print('카카오계정으로 로그인 실패 $error');
}
When using Login with Kakao Talk: Web or Login with Kakao Account: Web for the Redirect method, the service must request tokens with Get tokens API from the service server.
After getting tokens on the service server, request Retrieve user information to get the required information for signing up or logging in. To request Kakao APIs with Flutter SDK on the service client, pass the access token to the client and set tokens.
To request Get tokens or Retrieve user information API from the service server, use the REST API key.
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
- | Register platforms Activate Kakao Login |
Required | Required: Required consent item |
setToken() OAuthToken |
To store the tokens issued from the Kakao authorization server into the token manager of the Flutter SDK, call the setToken()
method.
// Change the token type to the type that can be used in SDK.
var tokenResponse = AccessTokenResponse.fromJson(response);
var token = OAuthToken.fromResponse(tokenResponse);
// Store tokens.
TokenManagerProvider.instance.manager.setToken(token);
Include two logics below when implementing Kakao Login with Flutter SDK.
isKakaoTalkInstalled()
to check whether Kakao Talk is available.Refer to the sample below.
// Login combination sample + Detailed error handling callback
bool talkInstalled = await isKakaoTalkInstalled();
// If Kakao Talk has been installed, log in with Kakao Talk. Otherwise, log in with Kakao Account.
if (talkInstalled) {
try {
OAuthToken token = await UserApi.instance.loginWithKakaoTalk();
print('Login succeeded. ${token.accessToken}');
} catch (e) {
print('Login failed. $e');
// After installing Kakao Talk, if a user does not complete app permission and cancels Login with Kakao Talk, skip to log in with Kakao Account, considering that the user does not want to log in.
// You could implement other actions such as going back to the previous page.
if (e is PlatformException && e.code == 'CANCELED') {
return;
}
// If a user is not logged into Kakao Talk after installing Kakao Talk and allowing app permission, make the user log in with Kakao Account.
try {
OAuthToken token = await UserApi.instance.loginWithKakaoAccount();
print('Login succeeded. ${token.accessToken}');
} catch (e) {
print('Login failed. $e');
}
}
} else {
try {
OAuthToken token = await UserApi.instance.loginWithKakaoAccount();
print('Login succeeded. ${token.accessToken}');
} catch (e) {
print('Login failed. $e');
}
}
bool talkInstalled = await isKakaoTalkInstalled();
if (talkInstalled) {
// Login with Kakao Talk. If Kakao Talk is not installed, the download page is open.
try {
await AuthCodeClient.instance.authorizeWithTalk(
redirectUri: '${REDIRECT_URI}',
);
} catch (error) {
print('Login with Kakao Talk fails $error');
}
} else {
// Login with Kakao Account
try {
await AuthCodeClient.instance.authorize(
redirectUri: '${REDIRECT_URI}',
);
} catch (error) {
print('Login with Kakao Account fails. $error');
}
}
You can request reauthentication regardless of a user's login status to enhance security. Set prompts
to [Prompt.login]
when you call loginWithKakaoAccount()
. Then, the login screen is prompted even though a user has already been logged in on the same web browser on the device.
try {
OAuthToken token = await UserApi.instance
.loginWithKakaoAccount(prompts: [Prompt.login]);
print('Login succeeds. ${token.accessToken}');
} catch (e) {
print('Login fails. $e')
}
You can request to prompt the Kakao Account sign-up page before Kakao Login. Set prompts
to [Prompt.create]
when you call loginWithKakaoAccount()
. The Kakao Login consent screen is presented after signing up for Kakao Account.
try {
OAuthToken token = await UserApi.instance
.loginWithKakaoAccount(prompts: [Prompt.create]);
print('Login succeeds. ${token.accessToken}');
} catch (e) {
print('Login fails. $e')
}
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
- | Register platforms Activate Kakao Login |
Required | - | hasToken() |
To check if a user has obtained an access token through Kakao Login, call the hasToken()
method defined in the UserApi
class. This API returns the presence of tokens as a boolean type.
Note that calling hasToken()
to check the token presence does not ensure the user's login status.
if (await AuthApi.instance.hasToken()) {
try {
AccessTokenInfo tokenInfo = await UserApi.instance.accessTokenInfo();
print('Succeeded in validating token ${tokenInfo.id} ${tokenInfo.expiresIn}');
} catch (e) {
if (e is KakaoException && e.isInvalidTokenError()) {
print('Token has expired.')
} else {
print('Failed to retrieve token information.')
}
try {
// Log in with Kakao Account
OAuthToken token = await UserApi.instance.loginWithKakaoAccount();
print('Login succeeds. ${token.accessToken}');
} catch (e) {
print('Login fails. $e')
}
}
} else {
print('There is no token.');
try {
OAuthToken token = await UserApi.instance.loginWithKakaoAccount();
print('Login succeeds. ${token.accessToken}');
} catch (e) {
print('Login fails. $e')
}
}
If the user has a valid access token, hasToken()
returns the token information through the AccessTokenInfo class. Then, you can call the token-based APIs with the user's access token.
If false
is returned, it means that the token is not valid, so you cannot retrieve the token information. For this case, implement a process for the user to log in to obtain tokens and the error handling process.
Name | Type | Description | Required |
---|---|---|---|
id | Int |
Service user ID. | X |
expiresIn | Int |
Validity period in seconds until the access token expires. | O |
appId | Int |
App ID that an access token has been issued for. | O |
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
- | Register platforms Activate Kakao Login |
Required | - | logout() |
To enable a user to log out, call the logout()
method in the UserApi
class. Then, the access and refresh token issued through the login process is deleted, and the user is logged out.
// Logout
try {
await UserApi.instance.logout();
print('Logout succeeds. Tokens are deleted from SDK.');
} catch (e) {
print('Logout fails. Tokens are deleted from SDK.')
}
Regardless of the result of the logout request, the Flutter SDK deletes the access token and refresh token so that the login session expires.
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
- | Register platforms Activate Kakao Login |
Required | - | unlink() UserIdResponse |
To unlink a user's Kakao Account from a service app, call the unlink()
method in the UserApi
class.
/// Unlink current user from the app.
try {
await UserApi.instance.unlink();
print('Unlink succeeds. Tokens are deleted from SDK.');
} catch (e) {
print('Unlink fails.')
}
If the request is successful, the session between an app and a user is disconnected, and the user is logged out as the issued access token and refresh token are deleted.
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
- | Register platforms Activate Kakao Login |
Required | - | accessTokenInfo() AccessTokenInfo |
To retrieve the token information of the user who is currently logged in, call the accessTokenInfo()
method in the UserApi
class. To check the validity of the tokens only, use this API rather than retrieving all user information.
// Retrieving token information
try {
AccessTokenInfo tokenInfo = await UserApi.instance.accessTokenInfo();
print('Succeeded in retrieving token information\nService user ID: ${tokenInfo.id}\nValidity period: ${tokenInfo.expiresIn} seconds');
} catch (e) {
print('Failed to retrieve token information.')
}
If the request is successful, accessTokenInfo()
returns the token information through the AccessTokenInfo class. If the access token expires, the access token is refreshed and new token information is returned.
You cannot trust the token information on the client side because it may expire if
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
- | Register platforms Activate Kakao Login Manage consent items |
Required | Required: All consent items to request user information |
me() User |
To retrieve user data, you must set consent items and obtain user's consent for the data that your service needs. If a user does not consent, you cannot get the user data. To check which a user has already agreed, you can call the Retrieving consent details API and check the agreed scopes first.
To retrieve the information of the user who is currently logged in, call the me()
method in the UserApi
class.
Name | Type | Description | Required |
---|---|---|---|
properties | List<String> |
List of property keys you want to retrieve. (Example: ["kakao_account.email","kakao_account.gender"] )See property_keys. |
X |
Here is an example of retrieving user information — Service user ID, email, nickname and profile thumbnail image URI.
// Retrieving user information
try {
User user = await UserApi.instance.me();
print('Succeeded in retrieving user information'
'\nService user ID: ${user.id}'
'\nEmail: ${user.kakaoAccount?.email}'
'\nNickname: ${user.kakaoAccount?.profile?.nickname}'
'\nProfile Thumbnail Image URI: ${user.kakaoAccount?.profile?.thumbnailImageUrl}');
} catch (e) {
print('Failed to retrieve user information');
}
me()
returns the user information through the User class.
Name | Type | Description | Required |
---|---|---|---|
id | Int |
Service user ID. | O |
hasSignedUp | Bool |
Only returned when the Auto-link setting is disabled. Whether the user is completely linked with (signed up) your app. false : Preregisteredtrue : Registered |
X |
connectedAt | DateTime |
The time when the user is linked with a service in UTC*. | X |
synchedAt | DateTime |
The time when the user is logged in through Kakao Sync Simple Signup in UTC*. This value is only passed for Kakao Sync service users. In this case, its value is the same as connected_at . |
X |
properties | Map<String, String> |
Additional user information saved on the Kakao platform to use it later. Refer to Prerequisites > Manage user properties. |
X |
kakaoAccount | Account |
Kakao Account information. To see what user data you can get, refer to User information included in Kakao Account. |
X |
* The time is based on Coordinated Universal Time(UTC), being 9 hours behind Korean Standard Time(KST). For the format of time, refer to RFC3339: Date and Time on the Internet.
Ensure that you need to handle exceptions for the following cases in which you cannot get the user information:
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
Required | Register platforms Activate Kakao Login Manage consent items |
Required | Required: Shipping information |
selectShippingAddresses() UserShippingAddresses |
To use this feature, set Custom URL scheme.
Prompts the shipping address picker to allow users to select a shipping address and returns the selected shipping address ID.
Call selectShippingAddresses()
in UserApi
. This API returns an addressId
for the selected shipping address. Request Retrieve shipping address with the addressId
to get the detailed shipping address.
try {
final addressId = await UserApi.instance.selectShippingAddresses();
final userShippingAddresses = await UserApi.instance.shippingAddresses(addressId: addressId);
Log.i(context, tag,
'Success\nService user ID: ${userShippingAddresses.userId}\n배송지: ${userShippingAddresses.shippingAddresses?.join('\n')}');
} catch(e) {
Log.e(context, tag, 'Failed to retrieve the shipping address $e');
}
Refer to Troubleshooting for the error cause.
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
Required | Register platforms Activate Kakao Login Manage consent items |
Required | Required: Shipping information |
shippingAddresses() UserShippingAddresses |
Retrieves shipping addresses saved in the user's Kakao Account.
Call shippingAddresses()
in UserApi
. Use the parameters below if necessary.
Name | Type | Description | Required |
---|---|---|---|
addressId | int |
Shipping address ID Used to specify an address ID to get a specific shipping address. Do not use together with fromUpdatedAt and pageSize . |
X |
fromUpdatedAt | DateTime |
If multiple shipping addresses are returned through multiple pages, only the shipping addresses that are changed after fromUpdateAt time return. The last shipping address on the previous page is used for an input value for the next page. If set to 0 , shipping addresses are retrieved from the beginning. |
X |
pageSize | Int |
Number of (two or more) shipping addresses displayed on a page. (Default: 10 ) |
X |
If not using Select shipping address API, the response may not include the shipping address when the user did not consent to the [Shipping information]. Refer to No shipping address in the response.
// Retrieve shipping address
UserShippingAddresses userShippingAddress;
try {
userShippingAddress = await UserApi.instance.shippingAddresses();
} catch (error) {
print('Failed to retrieve shipping address. $error');
return;
}
// Handling the response upon user agreement
if (userShippingAddress.shippingAddresses != null) {
print('Succeeded in retrieving shipping addresses'
'\nService user ID: ${userShippingAddress.userId}'
'\nShipping addresses: \n${userShippingAddress.shippingAddresses?.join('\n')}');
} else if (userShippingAddress.needsAgreement == false) {
print('User account does not have a shipping address'
'If required, select [Provision after collecting information] option in [My Application] > [Kakao Login] > [Consent items]');
} else if (userShippingAddress.needsAgreement == true) {
print('You must obtain consent to providing shipping address from a user.');
// Scope ID for the shipping addresses
List<String> scopes = ['shipping_address'];
// Request consent to providing shipping addresses
OAuthToken token;
try {
token = await UserApi.instance.loginWithNewScopes(scopes);
print('allowed scopes: ${token.scopes}');
} catch (error) {
print('Failed to get consent to providing shipping address $error');
}
// Retry after getting user consent
try {
UserShippingAddresses userShippingAddresses =
await UserApi.instance.shippingAddresses();
print('Succeeded in retrieving shipping address'
'\nService user ID: ${userShippingAddresses.userId}'
'\n${userShippingAddresses.shippingAddresses?.join('\n')}');
} catch (error) {
print('Failed to retrieve shipping address $error');
}
}
shippingAddresses()
returns the UserShippingAddresses
object. Refer to Troubleshooting for the error cause.
Name | Type | Description | Required |
---|---|---|---|
userId | Int |
Service user ID of a user who requested shipping addresses. | X |
shippingAddresses | List<ShippingAddress> |
List of shipping addresses that the user added. The default shipping address is displayed on the uppermost, and the rest addresses are sorted by last updated date in decending order. |
X |
needsAgreement | Bool |
Whether consent to shipping addresses is required. | X |
Name | Type | Description | Required |
---|---|---|---|
id | Int |
Shipping address ID. | O |
name | String |
Shipping address name. | X |
isDefault | Bool |
Whether the shipping address is a default address or not. | O |
updatedAt | DateTime |
The time when a user updated the shipping address. | X |
type | String |
Shipping address type. - OLD : Administrative address- NEW : Road name address. |
X |
baseAddress | String |
Base address that is automatically input when searching for a zipcode. | X |
detailAddress | String |
Detailed address that a user adds to the base address. | X |
receiverName | String |
Recipient name. | X |
receiverPhoneNumber1 | String |
Recipient phone number. | X |
receiverPhoneNumber2 | String |
Additional recipient phone number. | X |
zoneNumber | String |
New type of 5-digit postal code for a road name address system. Required for the road name address system. |
X |
zipCode | String |
Old type of 6-digit postal code for an administrative address system. Optional for the administrative address system because some old type of addresses may not have a zip code. |
X |
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
- | Register platforms Activate Kakao Login Manage user properties |
Required | - | updateProfile() User.properties |
You can store or update the additional user information needed for your service. Call the updateProfile()
method in the UserApi
class. You must pass the custom property keys and values that you want to upadate through properties
in a key-value pair. For example, if you want to update a user's clothing size, set properties
to {'clothing_size': 'small'}
.
Name | Type | Description | Required |
---|---|---|---|
properties | Map<String, String> |
User information to be updated. Check the property keys of user information that you want to update in [My Application] > [User Properties] by referring to Manage user properties. You can also add new property keys up to five. |
O |
// Storing or updating user's additional information
// Check the names of property keys that you can use in [My Application] > [User Properties] in Kakao Developers.
try {
// Data to be updated
Map<String, String> properties = {'${CUSTOM_PROPERTY_KEY}': '${CUSTOM_PROPERTY_VALUE}'};
await UserApi.instance.updateProfile(properties);
print('Storing user information succeeds.');
} catch (error) {
print('Storing user information fails. $error')
}
To check if the user information is successfully updated under the designated property keys, call the Retrieving user information API.
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
- | Register platforms Activate Kakao Login Manage consent items Advanced: Activate OpenID Connect(Optional) Set Simple Signup(for Kakao Sync) |
Required | Required: Required consent item |
loginWithNewScopes() |
You can request consent to access permission or specific personal information if the user has not agreed when the user logged in with Kakao. Before using this API, read Concepts > Request additional consent thoroughly for a better understanding.
Call the loginWithNewScopes()
method in the UserApi
class by passing the scopes of user information you want to request additional consent as arguments.
Name | Type | Description | Required |
---|---|---|---|
scopes | List<String> |
Pass the scope IDs of the User information. You can figure out each scope's ID in [My Application] > [Kakao Login] > [Consent Items]. IMPORTANT: If you implement OpenID Connect (OIDC), you must add openid to scopes along with the scope values you want to obtain consent. If not, OAuth is applied even though OIDC is enabled. |
O |
nonce | String |
Parameter to strengthen security. To prevent replay attacks, generate random strings and pass them as an argument. IMPORTANT: Allowed to set only when you integrate Kakao Login with OpenID Connect. |
X |
Here is an example that checks which scopes are required to get additional consent by checking the value of {FIELD_NAME}NeedsAgreement obtained through the Retrieving user information API.
/// Requesting additional consent
// You can request additional consent when the user attempts to use a service
// that requires specific user information and then obtain the user information as follows.
// * CAUTION: Consider the case that users refuse to consent to 'Optional consent' item
// to prevent a problem with the use of the service.
User user;
try {
user = await UserApi.instance.me();
} catch (error) {
print('Failed to retrieve user information. $error')
return;
}
// Check which scope are required to get additional consent.
List<String> scopes = [];
if (user.kakaoAccount?.emailNeedsAgreement == true) { scopes.add('account_email'); }
if (user.kakaoAccount?.birthdayNeedsAgreement == true) { scopes.add("birthday"); }
if (user.kakaoAccount?.birthyearNeedsAgreement == true) { scopes.add("birthyear");}
if (user.kakaoAccount?.ciNeedsAgreement == true) { scopes.add("account_ci"); }
if (user.kakaoAccount?.legalNameNeedsAgreement == true) { scopes.add("legal_name"); }
if (user.kakaoAccount?.legalBirthDateNeedsAgreement == true) { scopes.add("legal_birth_date"); }
if (user.kakaoAccount?.legalGenderNeedsAgreement == true) { scopes.add("legal_gender"); }
if (user.kakaoAccount?.phoneNumberNeedsAgreement == true) { scopes.add("phone_number"); }
if (user.kakaoAccount?.profileNeedsAgreement == true) { scopes.add("profile"); }
if (user.kakaoAccount?.ageRangeNeedsAgreement == true) { scopes.add("age_range"); }
// If a user has not granted permission to provide user information that is needed for your service, request additional consent with the `loginWithNewScopes()` method.
if (scopes.length > 0) {
print('Need to obtain consent from user.');
// If OpenID Connect (OIDC) is enabled,
// - When "openid" is added to `scopes`, OIDC is applied.
// - When "openid" is not added to `scopes`, OAuth 2.0 is applied.
// To use OIDC, add "openid" to `scopes`.
// scopes.add("openid");
OAuthToken token;
try {
token = await UserApi.instance.loginWithNewScopes(scopes);
print('allowed scopes: ${token.scopes}');
} catch (error) {
print('Failed to obtain additional consent. $error')
return;
}
// Retrieve the user information after obtaining consent.
try {
User user = await UserApi.instance.me();
print('Succeeded in retrieving user information.'
'\nID: ${user.id}'
'\nEmail: ${user.kakaoAccount?.email}'
'\nNickname: ${user.kakaoAccount?.profile?.nickname}'
'\nProfileImage: ${user.kakaoAccount?.profile?.thumbnailImageUrl}');
} catch (error) {
print('Failed to retrieve user information. $error')
}
}
If you develop a web app with the Flutter SDK, call the authorizeWithNewScopes()
method. Because the Consent screen is not presented automatically in a web app, you must manually implement the following process invoked when a user consents to new scopes:
// Request additional consent to the required scopes (Email and gender in this code snippet).
try {
await AuthCodeClient.instance.authorizeWithNewScopes(
scopes: [account_email, gender],
redirectUri: '${REDIRECT_URI}',
);
} catch (error) {
print('Failed to retrieve user information. $error');
}
// Implement a logic to request the new access token and store the new token.
loginWithNewScopes()
presents the Consent screen asking for consent to the requested scope. When a user chooses to provide the scope and selects [Accept and Continue] on the Consent screen, new tokens are issued, and the scope information is updated in the OAuthToken class.
On the other hand, authorizeWithNewScopes()
, used for a web app, only returns an authorization code.
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
- | Register platforms Activate Kakao Login Manage consent items |
Required | - | scopes() ScopeInfo |
To retrieve the detailed information of the scopes (consent items) that a user has agreed to, call the scopes()
method in the UserApi
class.
To retrieve the details of specific scopes only, you need to pass the scopes
parameter as an argument when calling scopes()
.
Name | Type | Description | Required |
---|---|---|---|
scopes | List<String> |
Used when you retrieve specific scopes only. List of scope IDs you want to retrieve by referring to the IDs set in [My Application] > [Kakao Login] > [Consent Items]. |
X |
try {
ScopeInfo scopeInfo = await UserApi.instance.scopes();
print('Succeeded in retrieving consent details succeeds.\n Scopes being used or agreed: ${scopeInfo.scopes}');
} catch (error) {
print('Failed to retrieve consent details. $error')
}
// List of the scope IDs that you want to retrieve
List<String> scopes = ['account_email', 'friends'];
try {
ScopeInfo scopeInfo = await UserApi.instance.scopes(scopes: scopes);
print('Succeeded in retrieving consent details succeeds.\n Scopes being used or agreed: ${scopeInfo.scopes}');
} catch (error) {
print('Failed to retrieve consent details. $error')
}
If the request is successful, the API returns the details of the scopes that you enabled in [My Application] > [Kakao Login] > [Consent Items] and that the user has consented through the scopeInfo
object. Even though your app is currently not using the scope but if a user has consented to the scope before, the scope is included in the response.
Name | Type | Description | Required |
---|---|---|---|
id | Int |
Service user ID. | O |
scopes | Scope |
List of scope information. | X |
Name | Type | Description | Required |
---|---|---|---|
id | String |
Scope ID. | O |
displayName | String |
Name or description of the scope (consent item) displayed on the Consent screen. | O |
type | ScopeType |
Scope type. PRIVACY or SERVICE . PRIVACY : scopes for Personal Information SERVICE : scopes for Permission |
O |
using | Bool |
Whether your app is using the scope.true : Using the scope. false : Not using the scope even though the user has agreed to. |
O |
agreed | Bool |
Whether the user has agreed to the scope.true : The user has agreed. false : The user has not agreed. |
O |
revocable | Bool |
Whether you can revoke this scope. Only returned if the user has agreed to the scope.( "agreed"=true )true : Possible to revoke the scope. false : Impossible to revoke the scope. |
X |
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
- | Register platforms Activate Kakao Login Manage consent items |
Required | - | revokeScopes() ScopeInfo |
To revoke the scope that a user has agreed to, call the revokeScopes()
method in the UserApi
class. You can only revoke the scope with "revocable":true
among the scopes retrieved through the Retrieving consent details API. If you request to revoke the scope that is not revocable, an error is returned.
You must pass the list of scope ID through the scopes
parameter when calling revokeScopes()
.
Name | Type | Description | Required |
---|---|---|---|
scopes | List<String> |
List of scope IDs you want to revoke. You can revoke only the scope with "revocable":true among the scopes retrieved through the Retrieving consent details API. |
O |
// List of the scope IDs that you want to revoke
List<String> scopes = ['account_email', 'legal_birth_date', 'friends'];
try {
ScopeInfo scopeInfo = await UserApi.instance.revokeScopes(scopes: scopes);
print('Succeeded in revoking consent.\n Scopes being used or agreed: ${scopeInfo.scopes}');
} catch (error) {
print('Failed to revoke consent. $error')
}
If the request is successful, the API returns the scopeInfo object that includes the changed details of each scope and whether a user has agreed to the scope.
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
Required | Register platforms Activate Kakao Login Manage consent items Advanced: Activate OpenID Connect(Optional) Set Simple Signup |
Required | Required: Required consent item |
isKakaoTalkInstalled() loginWithKakaoTalk() KakaoException loginWithKakaoAccount() KakaoException |
This API is only allowed for the service that adopted Kakao Sync. To see the advantages of Kakao Sync, refer to Concept > Kakao Sync. Before implementing this API, read Design service terms and policies.
This API enables you to request consent to specific service terms that a user has not consented to, regardless of whether the user has already signed up.
If your app is used for multiple services and each service requires consent to different service terms, or if a new required service term is added to your service, you can use this API. For more details, Design service terms and policies.
To request consent to specific scopes from a user, pass the list of service term tags through serviceTerms
as an argument when you call loginWithKakaoTalk()
or loginWithKakaoAccount()
.
If you do not add serviceTerms
when requesting an authorization code, the general Kakao Login API proceeds. In this case, you cannot request consent to the desired service terms. Also, if a user has already consented to all required service terms, the user is logged in without the Consent screen prompted. For more details, refer to FAQ.
Name | Type | Description | Required |
---|---|---|---|
serviceTerms | List<String> |
Tags for the service terms that are required to consent. | O |
// Getting consent to desired service terms
// Designate tags for the service terms that you want to get consent
// among the service terms registered in [My Application] > [Simple Signup] in Kakao Developers.
List<String> serviceTerms = ['service'];
// Request login with Kakao Talk using the serviceTerms parameter (same for Login with Kakao Account)
try {
OAuthToken token = await UserApi.instance
.loginWithKakaoTalk(serviceTerms: serviceTerms);
print('Login success. ${token.accessToken}');
} catch (error) {
print('Login fail. $error');
}
The response is returned through the OAuthToken object in the same as the Kakao Login.
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
Required: Kakao Sync | Register platforms Activate Kakao Login Manage consent items Set Simple Signup |
Required | - | serviceTerms() ServiceTerms UserServiceTerms |
This API is only allowed for the service that adopted Kakao Sync. To see the advantages of Kakao Sync, refer to Concept > Kakao Sync.
This API enables you to check the service terms that a user has consented to. Call the serviceTerms()
method defined in the UserApi
class.
Name | Type | Description | Required |
---|---|---|---|
result | String |
List of service terms to retrieve, use one of the followings.agreed_service_terms : List of service terms users have agreed to (default)app_service_terms : List of service terms enabled for the app |
X |
tags | List<String> |
Tags of service terms to retrieve, limited in the list specified by result . |
X |
try {
UserServiceTerms userServiceTerms =
await UserApi.instance.serviceTerms();
Log.i(context, tag,
'Success in retrieving consent details for service terms\nService user ID: ${userServiceTerms.id}\nService terms: \n${userServiceTerms.serviceTerms?.join('\n')}');
} catch (e) {
Log.e(context, tag, 'Failed to retrieve consent details for service terms', e);
}
serviceTerms()
returns the UserServiceTerms
object.
Name | Type | Description | Required |
---|---|---|---|
id | Long |
Service user ID. | O |
serviceTerms | List<ServiceTerms> |
List of service terms. | X |
Name | Type | Description | Required |
---|---|---|---|
tag | String |
Tags set in the service terms. | O |
required | Boolean |
Whether consent is required in the service terms. | O |
agreed | Boolean |
The consent status of the service terms.true : Agreedfalse : Disagreed |
O |
revocable | Boolean |
Whether consent is revocable in the service terms.true : Can be revokedfalse : Cannot be revoked, is in a disagreed state or is a required Term of ServiceNote: Only service terms with revocable consent are available for Revoke consent for service terms API requests. |
O |
agreedAt | Datetime |
The last time user agreed to the service terms. (RFC3339 internet date/time format) |
X |
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
Required: Kakao Sync | Register platforms Activate Kakao Login Manage consent items Set Simple Signup |
Required | - | revokeServiceTerms() RevokedServiceTerms UserRevokedServiceTerms |
This API is only allowed for the service that adopted Kakao Sync.
Revoke a service terms that a specific user has agreed to. Only service terms with a revocable
value of true
in the Retrieving consent details for service terms response can be revoked.
Call the revokeServiceTerms()
method defined in the UserApi
class. Specify the tags of the service terms you want to revoke consent for in tags
.
Name | Type | Description | Required |
---|---|---|---|
tags | List<String> |
Service terms tags to revoke. Note: Only service terms with a revocable value of true in the Retrieving consent details for service terms response can be revoked. |
O |
try {
UserRevokedServiceTerms userRevokedServiceTerms =
await UserApi.instance.revokeServiceTerms(tags: ['test_tag1', 'test_tag2']);
Log.i(context, tag,
'Success in revoking consent for service terms\nService user ID: ${userRevokedServiceTerms.id}\nRevoked service terms: \n${userRevokedServiceTerms.revokedServiceTerms?.join('\n')}');
} catch (e) {
Log.e(context, tag, 'Failed to revoke consent for service terms', e);
}
revokeServiceTerms()
returns the UserRevokedServiceTerms
object.
Name | Type | Description | Required |
---|---|---|---|
id | Long |
Service user ID. | O |
revokedServiceTerms | List<RevokedServiceTerms> |
List of revoked service terms Note: User non-consent or required service terms that cannot be revoked are not included. |
X |
Name | Type | Description | Required |
---|---|---|---|
tag | String |
Tag of revoked service terms | O |
agreed | Boolean |
The consent status of the service terms after revocation.true : Agreedfalse : Disagreed |
O |
Permission | Prerequisite | Kakao Login | User consent | Reference |
---|---|---|---|---|
Required | Register platforms Activate Kakao Login |
Required | - | signup() |
The Manual signup API is only for the app with the Auto-link option disabled. Before using this API, check out when to use this API and the cautions in REST API.
The Manual signup API manually links a user with your app to complete signup when the Auto-link is disabled. To figure out if the currently logged-in user needs to be linked with your app, check the value of hasSignedUp
by calling the Retrieving user information API and handle each case:
Return value | Status | Action |
---|---|---|
true |
The user is already linked with your app. | You do not need to call the Manual signup API. |
false |
The user is not linked with your app. | You must call signup() to link the user with your app manually. |
null |
Your app is using the Auto-link feature. | You do not need to call the Manual signup API. |
// Checking if user is linked with your app by calling the Retrieving user information API.
try {
User user = await UserApi.instance.me();
print('Succeeded in retrieving user information.'
'\nService user ID: ${user.id}'
'\nLinked status:: ${user.hasSignedUp}');
} catch (error) {
print('Failed to retrieve user information. $error');
}
If the return value of hasSignedUp
is false
and the user is ready to sign up, call the signup()
method to complete the signup. You can also request to store user information needed for your service with the properties
parameter.
Name | Type | Description | Required |
---|---|---|---|
properties | Map<String, String> |
A list of user information. Used when you want to store user information needed for your service when linking a user. Refer to Manage user properties. |
X |
// Requesting signup
try {
await UserApi.instance.signup();
print('signup succeeds.');
} catch (error) {
print('signup fails. $error')
}
If the request is successful, the user's service ID is returned.
Because the user's linked status is not provided even when the request is successful, request the Retrieving user information API again and check the value of hasSignedUp
to check the request result.