JavaScript SDK

This document describes how to integrate Kakao Login APIs into your service with Kakao SDK for JavaScript ("JavaScript SDK").

You can test the features described in this document in [Tools] > [JS SDK demo] menu.

JS SDK demooutlink

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.

Kakao Login button resource downloadoutlinkDesign Guide

Before you begin

Install SDK

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

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.

1. Obtain an authorization code 2. Obtain tokens 3. Handle users to complete login

Login

Basic information

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	authorize()

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.

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
prompt	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. - create: Used to prompt the Kakao Account sign-up page first. The Kakao Login consent screen will be present 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

* prompts: Deprecated, use prompt instead since 2.3.0 or higher version.

Sample

Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
});

Sample: Auto-login

Kakao.Auth.authorize({
  redirectUri: '${REDIRECT_URI}',
  prompt: 'none',
});

Set tokens

Basic information

Permission	Prerequisite	Kakao Login	User consent	Reference
-	-	Required	-	setAccessToken()

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

Basic information

Permission	Prerequisite	Kakao Login	User consent	Reference
-	Register platforms Activate Kakao Login	Required	-	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.

Sample

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

Unlink

Basic information

Permission	Prerequisite	Kakao Login	User consent	Reference
-	Register platforms Activate Kakao Login	Required	-	request()

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

Basic information

Permission	Prerequisite	Kakao Login	User consent	Reference
-	Register platforms Activate Kakao Login Manage consent items	Required	Required: All consent items to request user information	request()

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);
  });

Shipping address

Select shipping address

Basic information

Permission	Prerequisite	Kakao Login	User consent	Reference
Required	Register platforms Activate Kakao Login Manage consent items	Required	Required: Shipping information (shipping_address)	selectShippingAddress()

Prompts the shipping address picker to allow users to select a shipping address and returns the selected shipping address ID.

Call Kakao.Auth.selectShippingAddress(). The function returns an addressId for the selected shipping address. Request Retrieve shipping address with the addressId to get the detailed shipping address.

Refer to Troubleshooting for the error cause.

Parameter

Name	Type	Description	Required
forceMobileLayout	Boolean	Whether to fix the shipping address picker for the mobile layout. true: Mobile layout false: Responsive Layout (Default: false)	X
enableBackButton	Boolean	Whether to display a back button on the shipping address picker. true: Display false: Do not display (Default: true)	X

Response

Name	Type	Description	Required
address_id	Number	Shipping address ID. For the redirection method, address_id will be passed in the query string of returnUrl.	O
status	String	Whether the user selected a shipping address. success: The user selected a shipping address. error: An error occurred.	O

Sample

// Select shipping address
Kakao.Auth.selectShippingAddress()
  .then(function(selectedAddress) {
    // Retrieve shipping address
    return Kakao.API.request({
      url: '/v1/user/shipping_address',
      data: {
        address_id: selectedAddress.address_id,
      },
    });
  })
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Retrieve shipping address

Basic information

Permission	Prerequisite	Kakao Login	User consent	Reference
Required	Register platforms Activate Kakao Login Manage consent items	Required	Required: Shipping information (shipping_address)	request()

Retrieves shipping addresses saved in the user's Kakao Account.

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.

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.

Refer to Troubleshooting for the error cause.

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	Shipping address ID Used to 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

Basic information

Permission	Prerequisite	Kakao Login	User consent	Reference
-	Register platforms Activate Kakao Login Manage user properties	Required	-	request()

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

Basic information

Permission	Prerequisite	Kakao Login	User consent	Reference
-	Register platforms Activate Kakao Login Set Redirect URI Manage consent items Manage consent items Advanced: Activate OpenID Connect(Optional) Set Simple Signup(for Kakao Sync)	Required	Required: Required consent item	authorize()

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

Basic information

Permission	Prerequisite	Kakao Login	User consent	Reference
-	Register platforms Activate Kakao Login Manage consent items	Required	-	request()

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

Basic information

Permission	Prerequisite	Kakao Login	User consent	Reference
-	Register platforms Activate Kakao Login Manage consent items	Required	-	request()

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 because 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);
  });

Get consent to desired service terms

Basic information

Permission	Prerequisite	Kakao Login	User consent	Reference
Required	Register platforms Activate Kakao Login Set Redirect URI Manage consent items Manage consent items Advanced: Activate OpenID Connect(Optional) Set Simple Signup	Required	Required: Required consent item	authorize()

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.

Pass serviceTerms to the authorize() method as a parameter. Make sure to include all tags of the service 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 service 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',
});

Retrieve consent details for service terms

Basic information

Permission	Prerequisite	Kakao Login	User consent	Reference
Required: Kakao Sync	Register platforms Activate Kakao Login Manage consent items Set Simple Signup	Required	-	request()

This API enables you to check the service terms that a user has consented to.

Call the kakao.API.request() function, and set url to /v2/user/service_terms.

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

Parameter

Name	Type	Description	Required
url	String	Fixed as /v2/user/service_terms.	O
data	Object	Object that contains the parameter to be passed when requesting the API.	X

data: Retrieving consent details for service terms

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	String	Tags of service terms to retrieve, limited in the list specified by result. Pass multiple tags as a single comma (,) separated string.	X

Sample

Sample: Retrieving user agreed service terms

Kakao.API.request({
  url: '/v2/user/service_terms',
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Sample: Retrieving all service terms registered in app

Kakao.API.request({
  url: '/v2/user/service_terms',
  data: {
    result: 'app_service_terms',
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Sample: Retrieving specific service terms

Kakao.API.request({
  url: '/v2/user/service_terms',
  data: {
    tags: 'test_tag1,test_tag2'
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Revoke consent for service terms

Basic information

Permission	Prerequisite	Kakao Login	User consent	Reference
Required: Kakao Sync	Register platforms Activate Kakao Login Manage consent items Set Simple Signup	Required	-	request()

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 kakao.API.request() function, and set url to /v2/user/revoke/service_terms. Specify the tags of the service terms you want to revoke consent for in tags.

Kakao.API.request() returns Promise. If the promise is fulfilled, the information of the revoked service terms is returned. For the detailed response fields, refer to REST API.

Parameter

Name	Type	Description	Required
url	String	Fixed as /v2/user/revoke/service_terms.	O
data	Object	Object that contains the parameter to be passed when requesting the API.	O

data: Revoke consent for service terms

Name	Type	Description	Required
tags	String	Service terms tags to revoke. Pass multiple tags as a single comma (,) separated string, refer to Example. Note: Only service terms with a revocable value of true in the Retrieving consent details for service terms response can be revoked.	O

Sample

Kakao.API.request({
  url: '/v2/user/revoke/service_terms',
  data: {
    tags: 'test_tag1,test_tag2'
  },
})
  .then(function(response) {
    console.log(response);
  })
  .catch(function(error) {
    console.log(error);
  });

Advanced: Manual signup

Basic information

Permission	Prerequisite	Kakao Login	User consent	Reference
Required	Register platforms Activate Kakao Login	Required	-	request()

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

• Download JavaScript SDK
• API Reference for JavaScript →
• JavaScript SDK Demo →

Legacy

• Kakao Login for JavaScript SDK v1