페이지 이동경로
  • Docs>
  • Kakao Login>
  • JavaScript

Kakao Login

JavaScript SDK

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 provided by Kakao or customize buttons according to your service user interface by referring to the Design Guide.

Before you begin

Install SDK

Import the JavaScript SDK into your web page and initialize it by referring to Getting Started > JavaScript.

Register Web Platform

To use the JavaScript SDK, you must register the Web platform in advance. Go to [My Application] > [Platform] and register your site domains.

Understand login flow

To integrate Kakao Login into your web page with the JavaScript SDK, you need to fully understand how Kakao Login works by referring to REST API > Before you begin.

On mobile devices where Kakao Talk is installed, users can use the Kakao Simple Login function. Here is the flow of Kakao Simple Login.

Process of Kakao Login for JavaScript Step 1. Obtain an authorization code

If a user attempts Kakao Simple Login, Kakao.Auth.authorize() is invoked. Then, Kakao Talk is launched and the login page is prompted to the user.

Once the user approves permissions by clicking [Accept and Continue], the Kakao authorization server validates the user’s credentials and issues an authorization code to the specified redirect URI.

If Kakao Talk is not installed on a user's device, the Kakao Login page where the user can log in with a Kakao ID and password is open.

Step 2. Obtain tokens

Implement a process to get tokens by using a REST API.

When you request to exchange the authorization code for tokens, the Kakao authorization server validates the request and issues an access token and a refresh token.

Step 3. Handle users to complete login

When an access token is issued, you can call the Retrieving user information API by passing the issued access token. With the user data returned to this API, you can check if the user is registered in your service.

For a new user, register the user in your service's user database as a new member. For a registered user, you can create a login session for the user in your service and show a login page. To see how to handle users depending on the registration status, refer to Handling Kakao Login users.

Signup

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.

Login

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, Kakao Talk is launched and 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 in more detail, refer to Understand login flow.

IMPORTANT

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.

Parameter
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
prompts String Used for additional interactions when requesting an authorization code.
- login: Used to request reauthentication by presenting the Kakao Account Login screen to a user regardless of a user's login status to enhance security.
- none: Used to use the Auto-login function. Refer to Sample.
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
Sample
Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
});
Sample: Auto-login
Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
  prompts: 'none',
});

Set tokens

When the tokens are passed in your service server, you can use the access token to call the Kakao APIs such as Retrieving user information API. To do so, you need to assign your access token to SDK.

Call the Kakao.Auth.setAccessToken() function with the access token passed in the login response.

Kakao.Auth.setAccessToken('${ACCESS_TOKEN}');

Logout

To enable a user to log out, call the Kakao.Auth.logout() function.

Kakao.Auth.logout() returns Promise. If the promise is fulfilled, the tokens issued during the login process expire, and the user is logged out. After the user is logged out, you cannot call the Kakao APIs using the access token.

IMPORTANT

Kakao.Auth.logout() 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.

Sample
Kakao.Auth.logout()
  .then(function(response) {
    console.log(Kakao.Auth.getAccessToken()); // null
  })
  .catch(function(error) {
    console.log('Not logged in.');
  });

Unlink

To unlink a user's Kakao Account from your app, call the Kakao.API.request() function, and set url to /v1/user/unlink.

Kakao.API.request() returns Promise. If the promise is fulfilled, the user's service user ID is returned.

For more details on the unlink, see Concepts.

Parameter
Name Type Description Required
url String Fixed as /v1/user/unlink. O
Sample
Kakao.API.request({
  url: '/v1/user/unlink',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  }); 

Retrieve user information Consent required

IMPORTANT

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 retrieve the Kakao Account information of a logged-in user, 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.

Kakao.API.request() returns Promise. If the promise is fulfilled, the user information is returned. For the detailed user information in response, refer to REST API > Retrieve user information.

Parameter
Name Type Description Required
url String Fixed as /v2/user/me. O
data Object Object that contains the parameter to be passed when requesting the API. X
data: Retrieving user information
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
Sample
Kakao.API.request({
  url: '/v2/user/me',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });
Sample: Retrieving email and gender
Kakao.API.request({
  url: '/v2/user/me',
  data: {
    property_keys: ['kakao_account.email', 'kakao_account.gender'],
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Retrieve shipping address Consent required

This API enables you to retrieve shipping addresses saved in user's Kakao Account.

To retrieve shipping address,

  • You must enable the 'Shipping information (shipping_address)' scope.
  • Users must consent to the scope. If a user does not consent, you cannot get the user data even though you enabled the scope. If Kakao does not retain a user's shipping address, Kakao cannot provide the information to your service even when a user consents.

The shipping_address scope is inactivated by default. To set the scope to 'Optional consent', connect your app to a Biz Channel. If your service must get users' shipping addresses, set the scope to 'Required consent' by going through the Review for Provision of Personal Information provided by Kakao Sync and use the Provision after collecting information option.

Call the Kakao.API.request() function, and set url to /v1/user/shipping_address.

Kakao.API.request() returns Promise. If the promise is fulfilled, the user's shipping addresses are returned. For the detailed response fields, refer to REST API > Retrieve shipping address.

Parameter
Name Type Description Required
url String Fixed as '/v1/user/shipping_address'. O
data Object Object that contains the parameter to be passed when requesting the API. X
data: Retrieving shipping address
Name Type Description Required
address_id Number If there are multiple shipping addresses, specify an address ID to get a specific shipping address. X
from_updated_at Number If multiple shipping addresses return through multiple pages, only the shipping addresses that are changed after the updated_at 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
page_size Number Number of (two or more) shipping addresses displayed on a page.
(Default: 10)
X
Sample: Retrieving user's shipping addresses
Kakao.API.request({
  url: '/v1/user/shipping_address',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });
Sample: Retrieving a specific shipping address
Kakao.API.request({
  url: '/v1/user/shipping_address',
  data: {
    address_id: ${ADDRESS_ID},
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Store user information

You can store or update the additional user information needed for your service. To do so, you must register or check the custom property keys by referring to Manage user properties.

Call the Kakao.API.request() function, and set url to /v1/user/update_profile. You must pass the custom property keys and values that you want to update 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'.

Kakao.API.request() returns Promise. If the promise is fulfilled, the service user ID requested to update information is returned.

To check the updated user information, call the Retrieving user information API.

Parameter
Name Type Description Required
url String Fixed as '/v1/user/update_profile'. O
data Object Object that contains the parameter to be passed when requesting the API. X
data: Storing user information
Name Type Description Required
properties Object User information that you want to update in {key:value} format.
For key, check the registered property keys in [My Application] > [Kakao Login] > [User Properties].
O
Sample
Kakao.API.request({
  url: '/v1/user/update_profile',
  data: {
    properties: {
      '${CUSTOM_PROPERTY_KEY}': '${CUSTOM_PROPERTY_VALUE}',
    },
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Request additional consent Consent required

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.

To use this API,

  1. Enable the consent items for the scopes you want to obtain additional consent.
  2. Call the authorize() function that requests an authorization code with the scopes you want to request consent through the scope parameter.

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. The response is the same as the response of Getting authorization code API.

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
Sample: Request additional consent through OAuth protocol

Here is an example of requesting additional consent by passing the scopes of email and gender when calling authorize().

Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
  scope: 'account_email,gender',
});
Sample: Request additional consent through OIDC protocol
Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
  scope: 'openid,account_email,gender',
});

Retrieve consent details

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 consented 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.

Kakao.API.request() returns Promise. For the detailed response fields returned if the promise is fulfilled, refer to REST API > Retrieve consent details.

Parameter
Name Type Description Required
url String Fixed as /v2/user/scopes. O
data Object Object that contains the parameters to be passed when requesting the API. X
data: Retrieving consent details
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
Sample
Kakao.API.request({
  url: '/v2/user/scopes',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });
Sample: Checking the details of Email and gender scopes
Kakao.API.request({
  url: '/v2/user/scopes',
  data: {
    scopes: ['account_email', 'gender'],
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Revoke consent

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.

Kakao.API.request() returns Promise. For the detailed response fields returned if the promise is fulfilled, refer to REST API > Retrieve consent details since the response is the same as the Retrieving consent details API.

Parameter
Name Type Description Required
url String Fixed as /v2/user/revoke/scopes. O
data Object Object that contains the parameters to be passed when requesting the API. O
data: Revoking consent
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
Sample
Kakao.API.request({
  url: '/v2/user/revoke/scopes',
  data: {
    scopes: ['account_email', 'gender'],
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Check user agreed terms

IMPORTANT

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 terms and policies.

To check which terms a user has consented to when the user logs in, call the kakao.API.request() function, and set url to /v1/user/service/terms.

Kakao.API.request() returns Promise. If the promise is fulfilled, the information of the terms to which a user consented to is returned. For the detailed response fields, refer to REST API > Check user agreed terms.

Parameter
Name Type Description Required
url String Fixed as /v1/user/service/terms. O
data Object Object that contains the parameter to be passed when requesting the API. X
data: Checking user agreed terms
Name Type Description Required
extra String Used to retrieve all of the terms registered in your app.
In this case, set it to app_service_terms.
X
Sample
Kakao.API.request({
  url: '/v1/user/service/terms',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });
Sample: Requesting all terms registered in app
Kakao.API.request({
  url: '/v1/user/service/terms',
  data: {
    extra: 'app_service_terms',
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Get consent to desired terms

IMPORTANT

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 terms and policies.

This API enables you to request consent to a specific term that a user has not consented, regardless of whether the user has already signed up or not.

If your app is used for multiple services and each service requires consent to different terms, or if a new required term is added to your service, you can use this API. For more details, Design terms and policies.

Pass serviceTerms to the authorize() method as a parameter. Make sure to include all tags of the terms needed to get consent in a single String format by separating respective tags by comma(,).

If the request is successful, an authorization code is returned in the same way as the REST API. If the Consent screen is not prompted even after calling this API, refer to FAQ.

Parameter
Name Type Description Required
redirectUri String The URI used to get an authorization code. O
serviceTerms Sting[] Tags for the terms needed to get consent.
Tags should be in a single string format by separating respective tags by comma(,).
O
Sample
Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
  serviceTerms: 'tag1,tag2',
});

Advanced: Manual signup

IMPORTANT

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.

Kakao.API.request() returns Promise. If the promise is fulfilled, the user's service user ID is returned.

To check the request result in detail, call the Retrieving user information API again and see the value of has_signed_up and properties.status in the response.

Parameter
Name Type Description Required
url String Fixed as /v1/user/signup. O
data Object Object that contains the parameter to be passed when requesting the API. X
data: Manual signup
Name Type Description Required
properties Object Used when you want to store user properties when linking a user.
(Example: {key:value})
Refer to Manage user properties and Store user information.
X
Sample
Kakao.API.request({
  url: '/v1/user/signup',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });
Sample: Manual signup and update additional information
Kakao.API.request({
  url: '/v1/user/signup',
  data: {
    properties: {
      '${CUSTOM_PROPERTY_KEY}': '${CUSTOM_PROPERTY_VALUE}',
    },
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

See more

Legacy

IMPORTANT

It is highly recommended to upgrade to the new version of JavaScript SDK as soon as possible because the Legacy SDK may not be supported anymore.