This document describes how to integrate Kakao Login APIs into your service with Kakao SDK for JavaScript (hereinafter referred to as 'JavaScript SDK').
You can test the features described in this document in [Tools] > [JS SDK demo] menu.
For a Kakao Login button, you can download the resources that Kakao provides or customize it according to your service UI by referring to the Design guide.
To use the JavaScript SDK, you must register the Web platform in advance. Go to [My Application] > [Platform] and register your site domains.
You must include the JavaScript SDK in your web page and initialize it by referring to Getting started > JavaScript before calling the Login API.
The Simple Login functions to authenticate a user through Kakao Talk without inputting the Kakao Account information and get an authorization code. For the Simple Login function, call the Kakao.Auth.authorize()
function. If Kakao.Auth.authorize()
is invoked by the click event handler, the Consent screen is presented. If a user consents to the provision of their personal information and the use of your service, the Kakao authorization server issues the authorization code to the Redirect URI
of the service server with the HTTP response status code 302.
Afterthat, request to get tokens with the obtained authorization code to complete the login. To see how to set or check the Redirect URI, refer to Prerequisites > Set Redirect URI.
To see how to get an authorization code and tokens, refer to REST API API.
When you call 'Kakao.Auth.authorize' through JavaScript SDK, you must use your JavaScript key used to initialize the SDK. However, when you request to get tokens, use your REST API key.
The Kakao Login API functions to authenticate users on the Kakao platform and links their accounts with your app so that they can use your service. However, those who do not have Kakao Accounts need to create a new account in your service. In this case, you need to implement the process of creating a new account and updating the user information in your own service.
Name | Type | Description | Required |
---|---|---|---|
redirectUri | String |
A callback URL that the authorization code is redirected to. | O |
state | String |
If you add this parameter in the request, users are redirected to the page that they were viewing before authentication. If this parameter is included in the request, the same state parameter value with the request is sent to the response. |
X |
scope | String |
Used to request additional consent. | X |
throughTalk | Boolean |
Whether to use the Simple Login function. (Default: true ) |
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 |
Kakao.Auth.authorize({
redirectUri: '${REDIRECT_URI}'
});
When the access token and refresh token are passed in your service server, you can use the tokens to call the Kakao APIs such as Retrieving user information API with the issued tokens. To call other Kakao APIs besides the Login API using the JavaScript SDK, you need to assign your tokens into SDK. Call the Kakao.Auth.setAccessToken()
function with the access token passed in the login response to set it to use in the JavaScript SDK.
Kakao.Auth.setAccessToken(ACCESS_TOKEN);
The Logout API is used to let a user log out of the app. After the user is logged out, you cannot call the Kakao APIs using the corresponding access token since it expires.
Call the Kakao.Auth.logout function in the click event handler invoked when a user clicks [Logout], and then the tokens issued during the login process expire. If the request is successful, implement the process of logging out of a service internally
The Kakao.Auth.logout function makes the tokens expire, not make a user log out from your service or Kakao Account. Therefore, you need to implement the logout process internally in your service.
Type | Description | Required |
---|---|---|
Function() |
Callback function that gets invoked when tokens have expired. | X |
if (!Kakao.Auth.getAccessToken()) {
console.log('Not logged in.');
return;
}
Kakao.Auth.logout(function() {
console.log(Kakao.Auth.getAccessToken());
});
This API unlinks an app from a user's Kakao Account. Call the Kakao.API.request function in the click event handler invoked when a user requests to unlink.
Call the Kakao.API.request()
function, and set url
to /v1/user/unlink
.
You should implement the function of deleting a user's account in your service internally after unlinking the account from your app because the Kakao.API.request function does not affect the user data in the server.
Name | Type | Description | Required |
---|---|---|---|
url | String |
Fixed as /v1/user/unlink . |
O |
success | Function(Object) |
Callback function that gets invoked when the API request is successful. | X |
fail | Function(Object) |
Callback function that gets invoked if the API request is failed. | X |
always | Function(Object) |
Callback function that gets invoked regardless of API request results. | X |
Kakao.API.request({
url: '/v1/user/unlink',
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
},
});
To get a notification when a user unlinks from a service in person, use the 'Unlink callback' function. In the case of a user is unlinked through the Unlink API, the callback is not sent. Refer to Reference Information > Advanced > Unlink callback for the implementation method and the callback request information.
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 scopes a user has already agreed, you can call the Retrieving consent details API and check the agreed scopes first.
This API enables you to retrieve the Kakao Account information of a user who is logged into Kakao. You can request this API by calling a REST API with the kakao.API.request()
function. Call the kakao.API.request()
function, and set url
to /v2/user/me
. You can request a specific user information using the property_keys
parameter. For the request information, refer to REST API.
The response includes user information and is same as the REST API. Refer to Understand Concepts > User information for more details.
Name | Type | Description | Required |
---|---|---|---|
url | String |
Fixed as /v2/user/me . |
O |
success | Function(Object) |
Callback function that gets invoked when the API request is successful. | X |
fail | Function(Object) |
Callback function that gets invoked when the API request is failed. | X |
always | Function(Object) |
Callback function that gets invoked regardless of API request results. | X |
data | Object |
Object that contains the parameter to be passed when requesting the API. Refer to data: Retrieving user information for more details. |
X |
Name | Type | Description | Required |
---|---|---|---|
property_keys | String[] |
Use this parameter to specify the scopes of user information to be requested in ["key1","key2"] format. | X |
Kakao.API.request({
url: '/v2/user/me',
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
});
Kakao.API.request({
url: '/v2/user/me',
data: {
property_keys: ["kakao_account.email","kakao_account.gender"]
},
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
});
This API stores or update additional user information on the Kakao platform to use in a service, which is called 'User properties'. You must use the property keys designated in [My Application] > [Kakao Login] > [User Properties].
You can request this API by calling a REST API with the kakao.API.request()
function. Call the Kakao.API.request()
function, and set url
to /v1/user/update_profile
. For example, if you want to store or update gender
and age
in your app, you must pass properties
.
If the request is successful, the service user ID requested to store information is returned in the same way as the REST API. To check the updated user information, call the Retrieving user information API.
Name | Type | Description | Required |
---|---|---|---|
url | String |
Fixed as '/v1/user/update_profile' . |
O |
success | Function(Object) |
Callback function that gets invoked when the API request is successful. | X |
fail | Function(Object) |
Callback function that gets invoked when the API request is failed. | X |
always | Function(Object) |
Callback function that gets invoked regardless of API request results. | X |
data | Object |
Object that contains the parameter to be passed when requesting the API. Refer to data: Storing user information for more details. |
X |
Name | Type | Description | Required |
---|---|---|---|
properties | Object |
User information that you want to update in {key:value} format. | O |
Kakao.API.request({
url: '/v1/user/update_profile',
data: {
properties: {
gender: 'female',
age: '22',
},
},
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
});
This API prompts the Consent screen to request additional permission or specific personal information for the service if the user has not agreed once logging in with Kakao. Before using this API, read Understand concepts > Request additional consent thoroughly for a better understanding.
To use this API,
authorize()
function that requests an authorization code with the scopes you want to request consent through the scope
parameter.Name | Type | Description | Required |
---|---|---|---|
redirectUri | String |
URI to get the authorization code. | O |
scope | String |
Scope ID of the User information you want to request additional consent. You can pass multiple scopes by separating by comma(,) as a string without space. You can figure out each scope's ID in [My Application] > [Kakao Login] > [Consent Items]. (Example: 'scope: 'account_email,gender' ) IMPORTANT: If you implement OpenID Connect (OIDC), you must add openid to scope along with the scope values you want to obtain consent. If not, OAuth is enabled even though you enabled OIDC.(Example: scope: 'openid,account_email,gender' ) |
O |
state | String |
Parameters to be maintained during the login process. | 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 |
The response is the same as the response of Getting authorization code API. If the request is successful, the Consent screen that includes the requested scope as a consent item is presented. When a user selects [Accept and Continue] on the Consent screen, the request is successfully completed. If the user selects [Cancel], the request is failed.
Here is an example of requesting additional consent by passing the scopes of email and gender when calling authorize
.
Kakao.Auth.authorize({
redirectUri: 'https://developers.kakao.com/kakaoLogin.jsp',
scope: 'account_email,gender'
});
Kakao.Auth.authorize({
redirectUri: 'https://developers.kakao.com/kakaoLogin.jsp',
scope: 'openid,account_email,gender'
});
If you want to present the Consent screen as a pop-up window or the client handles all authentication processes, call theKakao.Auth.login
.
Kakao.Auth.login({
scope: 'account_email,gender',
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
});
This API enables you to retrieve the detailed information of the scopes (consent items) that a user has agreed to. You can check all scopes set in [My Application] > [Kakao Login] > [Consent Items] and the details of the scopes. If a user has consent to the scope before, the scope is included in the response even though your app is currently not using the scope.
Call the Kakao.API.request()
function, and set url
to /v2/user/scopes
. You can also designate the scopes you want to check the details by specifying the scopes
parameter. If the request is successful, the response includes only the detailed information of the specified scopes in the same way as the REST API. Refer to REST API > Retrieve consent details for more details.
Name | Type | Description | Required |
---|---|---|---|
url | String |
Fixed as /v2/user/scopes . |
O |
success | Function(Object) |
Callback function that gets invoked when the API request is successful. | X |
fail | Function(Object) |
Callback function that gets invoked when the API request is failed. | X |
always | Function(Object) |
Callback function that gets invoked regardless of API request results. | X |
data | Object |
Object that contains the parameters to be passed when requesting the API. Refer to data: Retrieving consent details for more details. |
X |
Name | Type | Description | Required |
---|---|---|---|
scopes | String[] |
Used when you retrieve specific scopes only. List of scope IDs you want to retrieve. You can figure out each scope's ID in [My Application] > [Kakao Login] > [Consent Items]. (Example: ["account_email","gender"] ) |
X |
Kakao.API.request({
url: '/v2/user/scopes',
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
});
Kakao.API.request({
url: '/v2/user/scopes',
data: {
scopes: ["account_email","gender"]
},
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
});
This API revokes the scope that a user has agreed to. 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.
Call the Kakao.API.request()
function, and set url
to /v2/user/revoke/scopes
. The response is the same as the response of Retrieving consent details API. Refer to REST API > Retrieving consent details.
Name | Type | Description | Required |
---|---|---|---|
url | String |
Fixed as /v2/user/revoke/scopes . |
O |
success | Function(Object) |
Callback function that gets invoked when the API request is successful. | X |
fail | Function(Object) |
Callback function that gets invoked when the API request is failed. | X |
always | Function(Object) |
Callback function that gets invoked regardless of API request results. | X |
data | Object |
Object that contains the parameters to be passed when requesting the API. Refer to data: Revoking consent for more details. |
O |
Name | Type | Description | Required |
---|---|---|---|
scopes | 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.You can figure out each scope's ID in [My Application] > [Kakao Login] > [Consent Items]. (Example: ["account_email","gender"] ) |
O |
Kakao.API.request({
url: '/v2/user/revoke/scopes',
data: {
scopes: ["account_email","gender"]
},
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
});
If you need to display the Consent screen as a pop-up window or if the whole authentication should be completed from the client-side, use the Kakao.Auth.login()
function.
If you call this function in the click event handler, you can present the Kakao Login Consent screen and then get consent to provide user information and use of the service from users.
If the login request is successful, an access token is issued. Since the access token is used internally in the SDK, you do not need to process it separately. However, you need to process a login or signup process in your service for a user who succeeded in logging in using the success callback function.
Name | Type | Description | Required |
---|---|---|---|
success | Function(Object) |
Callback function that gets invoked when the API request is successful. For the response, refer to the REST API > Getting tokens. |
X |
fail | Function(Object) |
Callback function that gets invoked when the API request is failed. | X |
always | Function(Object) |
Callback function that gets invoked regardless of API request results. | X |
scope | String |
Used to request additional consent. Pass the scope IDs of the User information. You can figure out each scope's ID in [My Application] > [Kakao Login] > [Consent Items]. For multiple scopes, separate them by comma(,) as a string without space. (Example: 'account_email,gender' )IMPORTANT: If you implement OpenID Connect (OIDC), you must add openid to scope along with the scope values you want to obtain consent. If not, OAuth is enabled even though you enabled OIDC.(Example: scope: 'openid,account_email,gender' ) |
X |
persistAccessToken | Boolean |
Stores the access token in the local storage to use it even after the session ends. (Default: true ) |
X |
throughTalk | Boolean |
Whether to use the Simple Login function. (Default: true ) |
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 and pass scope . |
X |
Kakao.Auth.login({
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
},
});
This example shows how to add an event handler to the Kakao Login button using createLoginButton
.
Kakao.Auth.createLoginButton({
container: '${CONTAINER_ID}',
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
},
});
To enhance secruity, the JavaScript SDK does not handle refresh token any more. The refresh token information ('refresh_token' and 'refresh_token_expires_in') issued through the Kakao.Auth.login and Kakao.Auth.createLoginButton function when logging in have been deprecated as of July 27, 2020. If your service is using a refresh token, you must request an authorization code using the Kakao.Auth.authorize function and get tokens using a REST API. Refer to Notice.
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 has_signed_up
in the response of the Retrieving user information API and handle each case:
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 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.Call the Kakao.API.request()
function, and set url
to /v1/user/signup
. If you want to store the user's information when the user is linked to your app, pass properties
in data
.
If the request is successful, id
is returned in the same way as the REST API. Refer to REST API > Advanced: Manual signup for more details.
Since the Manual signup API only returns the service user ID if successful, call the Retrieving user information API again and see the value of has_signed_up
and properties
to check the request result in detail.
Name | Type | Description | Required |
---|---|---|---|
url | String |
Fixed as /v1/user/signup . |
O |
success | Function(Object) |
Callback function that gets invoked when the API request is successful. | X |
fail | Function(Object) |
Callback function that gets invoked if the API request is failed. | X |
always | Function(Object) |
Callback function that gets invoked regardless of API request results. | X |
data | Object |
Object that contains the parameter to be passed when requesting the API. Refer to data: Manual signup for more details. |
X |
Name | Type | Description | Required |
---|---|---|---|
properties | Object |
Used when you want to store user properties when linking a user. (Example: {key:value}) Refer to User properties and Store user information. |
X |
Kakao.API.request({
url: '/v1/user/signup',
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
},
});
Kakao.API.request({
url: '/v1/user/signup',
data: {
properties: {
nickname: 'Apeach',
age: '22',
},
},
success: function(response) {
console.log(response);
},
fail: function(error) {
console.log(error);
}
});