REST API

This document describes how to integrate Kakao Login APIs into your service with a REST API.

You can test some features described in this document in [Tools] > [REST API Test].

REST API Test Tooloutlink

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

REST API is a suitable architectural style to implement Kakao Login both in PC and on the mobile web. To implement Kakao Login using a REST API, you need to get an authorization code, and then get tokens with the obtained authorization code as follows.

1. If a user clicks [Login with Kakao], the user is asked to log in on the Kakao login page provided by Kakao.
2. When the user logs in with Kakao Account information on the page, the Getting authorization code API is invoked. This API prompts the Consent screen to a user. If a web browser retains a session cookie that includes the Kakao Account information, the Consent screen is presented to the user without asking a login with Kakao Account.
3. Once the user approves permissions by clicking [Accept and Continue], the Kakao authorization server validates the user’s credentials and issues an authorization code. The user is redirected back to your app with the authorization code via redirect_uri.
4. Your app requests an access token and a refresh token with the issued authorization code by calling the Getting tokens.
5. The Kakao authorization server validates the request, issues an access token and a refresh token based on the authorization code, and provides authorization. See Token information to learn more about the access token and refresh token.

Get authorization code

Basic information

Method	URL	Authorization
GET	https://kauth.kakao.com/oauth/authorize	-

Permission	Prerequisite	Kakao Login	User consent
-	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

This is the first step of the Kakao Login process. The Getting authorization code API presents the Consent screen to a user when the user clicks [Login], and then requests an authorization code. You can configure the Consent screen in [My Application] > [Kakao Login] > [Consent Items].

The login process flows differently depending on the session of the Kakao Account when requesting an authorization code. If a browser does not retain a session cookie that includes the Kakao Account information, the Consent screen is presented after the user inputs Kakao Account information or logs in with Kakao Talk for authorization. If the session is retained, the Consent screen is presented to the user without any additional process.

When the user consents and clicks [Accept and Continue] on the Consent screen, the Kakao authorization server sends an authorization code as a query string to the redirect_uri in the header field Location with the response code 'HTTP 302 Redirect'. If a user clicks [Cancel], the server adds an error code as a query string to redirect_uri.

The service server must process the request received through redirect_uri, such as getting an authorization code or presenting a specific web page. The obtained authorization code is used to get tokens.

If you encounter the "Invalid redirect" error or the Consent screen does not appear, see FAQ.

Request

Query parameter

Name	Type	Description	Required
client_id	String	REST API key that Kakao issues when you register an app. You can check Your REST API key in [My Application] > [App Keys].	O
redirect_uri	String	Callback URL that the authorization code is redirected to. IMPORTANT: This must coincide with the Redirect URI registered in [My Application] > [Kakao Login]. Otherwise, KOE006 error occurs.	O
response_type	String	Fixed to code.	O
prompt	String	Used to request reauthentication by selecting whether to present an interactive UI. Pass a list of string values delimited by comma(,). - login: Used when requesting reauthentication even though a user has already been authenticated by presenting the Kakao Account Login screen to a user. Not available in Kakao Talk in-app browser. - none: Used to use the Auto-login function. - 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
login_hint	String	Used to request with Login hint A value to fill in ID field of the Kakao Account login page. Note: Users can login with their email, phone number, and ID of Kakao Mail on the Kakao Account login page.	X
service_terms	String	Used to request Get consent to desired service terms API. Tags of desired service terms. You can find tag values in [My Application] > [Kakao Login] > [Simple Signup]. Pass the tag values as a comma-separated string.	X
state	String	Parameter to strengthen security. Random string generated by your app to keep the state between the request and callback. It is recommended to use this parameter to protect from Cross-Site Request Forgery(CSRF).	X
nonce	String	Parameter to strengthen security. To prevent replay attacks, generate random strings and include the request. IMPORTANT: Allowed to set only when you integrate Kakao Login with OpenID Connect.	X

* auth_type: Deprecated. Use prompt instead.

Response

The response is redirected to the redirect_uri as a GET request with the query parameters below.

Query parameter

Name	Type	Description	Required
code	String	Authorization code that is used to get an access token.	X
error	String	Error code that is returned if authentication fails. Refer to Troubleshooting.	X
error_description	String	Error message that is returned if authentication fails. Refer to Troubleshooting.	X
state	String	If state is included in the request, the same value as the request must be returned.	X

Sample

Request

https://kauth.kakao.com/oauth/authorize?response_type=code&client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}

Request: For OpenID Connect, with nonce included

https://kauth.kakao.com/oauth/authorize?response_type=code&client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&nonce=${NONCE}

Response: Success, if user selects [Accept and Continue]

HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?code=${AUTHORIZATION_CODE}

Response: Fail, if user selects [Cancel]

HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?error=access_denied&error_description=User%20denied%20access

Get tokens

Basic information

Method	URL	Authorization
POST	https://kauth.kakao.com/oauth/token	-

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

The Getting tokens API enables you to get tokens with the obtained authorization code. When you obtain the tokens, the login process is complete.

Send a POST request with the required parameters.

In response to the request, an access token and a refresh token, token type, and validity period are returned in JSON format. Refer to Token information for more detailed information about tokens and its validity period.

The issued access token is used to call the token-based APIs, such as the Retrieving user information API, that requires Kakao Login to get tokens for authorization. You can retrieve token information or refresh the tokens using the refresh token issued with the access token.

Request

Header

Name	Description	Required
Content-Type	Content-Type: application/x-www-form-urlencoded;charset=utf-8 The data type of the request.	O

Body

Name	Type	Description	Required
grant_type	String	Fixed to authorization_code.	O
client_id	String	REST API key that Kakao issues when you register an app. You can check Your REST API key in [My Application] > [App Keys].	O
redirect_uri	String	Callback URL that the authorization code is redirected to. IMPORTANT: This must coincide with redirect_uri used when requesting an authorization code.	O
code	String	The obtained authorization code through the Getting authorization code API.	O
client_secret	String	An additional code to strengthen security when issuing tokens. You can create a client secret code by clicking [Create code] on the [My Application] > [Kakao Login] > [Security] page. You must add this parameter if 'Client Secret' is activated on this page. Otherwise, the token is not issued from the authorization server.	X

Response

Body

Name	Type	Description	Required
token_type	String	A type of a token. Fixed to bearer.	O
access_token	String	One of the tokens that authorizes you to call Kakao APIs and identifies users.	O
expires_in	Integer	Validity period in seconds until the access token expires.	O
refresh_token	String	One of the tokens that is used to gain new tokens.	O
refresh_token_expires_in	Integer	Validity period in seconds until the refresh token expires.	O
scope	String	Scopes of user information to be retrieved with the issued access token. For multiple scopes, each scope is separated by space.	X
id_token	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

Sample

Request

curl -v -X POST "https://kauth.kakao.com/oauth/token" \
    -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
    -d "grant_type=authorization_code" \
    -d "client_id=${REST_API_KEY}" \
    --data-urlencode "redirect_uri=${REDIRECT_URI}" \
    -d "code=${AUTHORIZATION_CODE}"

Response: If OAuth request is successful

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "token_type":"bearer",
    "access_token":"${ACCESS_TOKEN}",
    "expires_in":43199,
    "refresh_token":"${REFRESH_TOKEN}",
    "refresh_token_expires_in":5184000,
    "scope":"account_email profile"
}

Response: If OIDC request is successful

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "token_type":"bearer",
    "access_token":"{ACCESS_TOKEN}",
    "expires_in":43199,
    "refresh_token":"{REFRESH_TOKEN}",
    "refresh_token_expires_in":5184000,
    "scope":"openid account_email profile",
    "id_token":"${ID_TOKEN}"
}

Auto-login from Kakao Talk

Basic information

Method	URL	Authorization
GET	https://kauth.kakao.com/oauth/authorize	-

Permission	Prerequisite	Kakao Login	User consent
-	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

The Auto-login from Kakao Talk (Auto-login, for short) is an extended feature of Kakao Login, which allows users to log in automatically from the in-app browser, and shows a different page depending on the user's login status. Fore more information, refer to Concepts.

After checking that the user browser is the Kakao Talk in-app browser, request an authorization code using a REST API. To use the Auto-login feature, you must add prompt=none in the request. If not, general Kakao Login proceeds instead of the Auto-login.

You can get the authorization code through redirect_uri that the Kakao authorization server passes to as the query string.

If a user has signed up with the Kakao Account through Kakao Sync, only the authorization code is returned in the response. In this case, show the user your service page in a logged-in state after requesting an access token and a refresh token with the authorization code.

On the other hand, if a user has not signed up yet, an error is returned. In this case, show the user your service page in a logged-out state. You also need to implement the login process without Auto-login when a user takes an action that requires login or signup.

Request

Query parameter

Name	Type	Description	Required
client_id	String	REST API key that Kakao issues when you register an app. You can check Your REST API key in [My Application] > [App Keys].	O
redirect_uri	String	Callback URL that the authorization code is redirected to.	O
response_type	String	Fixed to code.	O
prompt	String	To use the Auto-login feature, you must set it to none. If a user's action is required to get an authorization code, an error is returned.	O
state	String	Parameter to strengthen security. Random string generated by your app to keep the state between the request and callback. It is recommended to use this parameter to protect from Cross-Site Request Forgery(CSRF).	X

Response

The response is redirected to the redirect_uri as a GET request with the query parameters below.

Query parameter

Name	Type	Description	Required
code	String	authorization_code that returns if your request succeeds.	X
state	String	If this parameter is included in the request, the same value as the request must be returned.	X
error	String	Error code that is returned if your request fails.	X
error_description	String	Error message that is returned if your request fails.	X

Sample

Request

https://kauth.kakao.com/oauth/authorize?response_type=code&client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&prompt=none

Response: Success

HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?code=${AUTHORIZATION_CODE}

Response: Fail, if user's consent is required

HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?error=consent_required&error_description=user%20consent%20required.

Response: Fail, if user authentication is required

HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?error=login_required&error_description=user%20authentication%20required.

Logout

Basic information

Method	URL	Authorization
POST	https://kapi.kakao.com/v1/user/logout	Access token Service app admin key

Permission	Prerequisite	Kakao Login	User consent
-	Register platforms Activate Kakao Login	Required	-

To enable a user to log out, call the Logout API, and then the issued access token and the refresh token expire if the request succeeds.

When you request, you can use either an access token or an admin key.

• If you use an access token, only the requested access token expires. Then, the user is logged out on all devices where the corresponding access token is used.
• If you use an admin key with a user's service user ID, all valid access tokens of the user expire. The user is logged out on all devices.

If the request is successful, the user's service user ID is returned. After the user is logged out, Kakao APIs cannot be called using the user information in the service.

Even after a user logs out of the service as the tokens expire, the Kakao Account session is still retained on the web browser. Implement subsequent actions after users log out such as redirecting them to the main web page of your service.

If you need to have a user log out of the Kakao Account as well as the service on a web browser, you need to expire the Kakao Account session by using an add-on feature, Logout of service and Kakao Account.

Request: Using access token

Header

Name	Description	Required
Authorization	Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication.	O

Request: Using service app admin key

Header

Name	Description	Required
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication.	O

Body

Name	Type	Description	Required
target_id_type	String	A type of a service user ID. Fixed to user_id.	O
target_id	Long	Service user ID to be logged out of the service.	O

Response

Body

Name	Type	Description	Required
id	Long	Service user ID that has been logged out.	O

Sample

Request: Using access token

curl -v -X POST "https://kapi.kakao.com/v1/user/logout" \
    -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"

Request: Using service app admin key

curl -v -X POST "https://kapi.kakao.com/v1/user/logout" \
    -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    -d "target_id=123456789" 

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":123456789
}

Logout of service and Kakao Account

Basic information

Method	URL	Authorization
GET	https://kauth.kakao.com/oauth/logout	-

Permission	Prerequisite	Kakao Login	User consent
-	Register platforms Activate Kakao Login Set Logout Redirect URI	Required	-

This feature is an add-on to the Logout API, allowing a user to log out of the service along with the user's Kakao Account session on a web browser expired. Refer to Concepts to learn more about this feature and Prerequisites.

The basic Logout functions to limit requesting Kakao APIs with the corresponding user information as the tokens expire. In this case, users need to log out of a service and Kakao Account respectively. On the other hand, with the 'Logout of service and Kakao Account' feature, users can log out of the service right after logging out of Kakao Account by redirecting to the set Logout Redirect URI.

Note that the request URL and parameters are different depending on logout types because the logout process flows differently. Set client_id to the app's REST API key and Logout Redirect URI to the service server address where logging out of the service will be proceeded as query parameters, and send a GET request. If you want to keep some value during the logout process, put it in state parameter.

You need to implement the subsequent process internally according to the logout result passed to Logout Redirect URI. The Kakao authorization server does not get the result of the logout process from the service.

Request

Query parameter

Name	Type	Description	Required
client_id	String	REST API key that Kakao issues when you register an app. You can check Your REST API key in [My Application] > [App Keys].	O
logout_redirect_uri	String	Logout Redirect URI where logging out of the service will be proceeded. One of the URIs set on the [My Application] > [Kakao Login] > [Logout Redirect URI] page .	O
state	String	Parameter to strengthen security. Random string generated by your app to keep the state between the request and callback.	X

Response

The response is redirected to the logout_redirect_uri as a GET request with the query parameters below.

Query parameter

Name	Type	Description	Required
state	String	If state is included in the request, the same value as the request must be returned.	X

Sample

Request

curl -v -G GET "https://kauth.kakao.com/oauth/logout?client_id=${YOUR_REST_API_KEY}&logout_redirect_uri=${YOUR_LOGOUT_REDIRECT_URI}"

Response

HTTP/1.1 302 Found
Location: ${LOGOUT_REDIRECT_URI}?state=${STATE}

Unlink

Basic information

Method	URL	Authorization
POST	https://kapi.kakao.com/v1/user/unlink	Access token Service app admin key

Permission	Prerequisite	Kakao Login	User consent
-	Register platforms Activate Kakao Login	Required	-

When using a REST API, you can request the Unlink API in two ways — with an access token or an Admin key. We provide an alternative way just in case you cannot request the Unlink API with an access token such as if the service is terminated.

Include the access token in the request header, and send a POST request. If you request the Unlink API using an Admin key, you must specify a user to be logged out in the request.

When the Unlink API request succeeds, the user is also logged out and the access and refresh tokens expire. If the request is successful, the service user ID is returned.

For more details on the unlink, see Concepts.

Request: Using access token

Header

Name	Description	Required
Authorization	Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication.	O

Request: Using service app admin key

Header

Name	Description	Required
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication.	O

Body

Name	Type	Description	Required
target_id_type	String	A type of a service user ID. Fixed to user_id.	O
target_id	Long	Service user ID to be unlinked from the service.	O

Response

Body

Name	Type	Description	Required
id	Long	Service user ID that has been successfully unlinked from the service.	O

Sample

Request: Using access token

curl -v -X POST "https://kapi.kakao.com/v1/user/unlink" \
    -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"

Request: Using service app admin key

curl -v -X POST "https://kapi.kakao.com/v1/user/unlink" \
    -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    -d "target_id=123456789" 

Response

{
    "id": 123456789
}

Retrieve token information

Basic information

Method	URL	Authorization
GET	https://kapi.kakao.com/v1/user/access_token_info	Access token

Permission	Prerequisite	Kakao Login	User consent
-	Register platforms Activate Kakao Login	Required	-

The Retrieving token information API retrieves the validity period of the access and refresh tokens in seconds, app ID and service user ID. Include the access token in the request header, and send a GET request.

If the request is successful, the detailed information about the token is returned in JSON format. If an error occurs, see below or Reference Information > REST API > Response code.

Code	Description	HTTP Status
-1	Internal error occurs temporarily on the Kakao platform service. It is recommended to handle this temporary error with an error message without making tokens expire or log out.	400
-2	If the required parameter is not included in the request or its data type has something wrong or out of range. If the given token information has something wrong with the format, check if you use the precise access token when requesting.	400
-401	If you request API using the expired token or invalid app key. If you use the wrong or invalid token value, you need to refresh the access token.	401

For other errors besides these cases above, it is recommended to log a user out because the status of an app, the user, or tokens may not be valid.

Request

Header

Name	Description	Required
Authorization	Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication.	O

Response

Body

Name	Type	Description	Required
id	Long	Service user ID.	O
expires_in	Integer	Validity period in seconds until the access token expires. NOTE: expiresInMillis has been deprecated and replaced with expires_in.	O
app_id	Integer	App ID that an access token has been issued for. NOTE: appId has been deprecated and replaced with app_id.	O

Sample

Request

curl -v -G GET "https://kapi.kakao.com/v1/user/access_token_info" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"

Response

HTTP/1.1 200 OK
{
    "id":123456789,
    "expires_in": 7199,
    "app_id":1234
}

Refresh tokens

Basic information

Method	URL	Authorization
POST	https://kauth.kakao.com/oauth/token	-

Permission	Prerequisite	Kakao Login	User consent
-	Register platforms Activate Kakao Login	Required	-

The Refreshing tokens API refreshes the access and refresh tokens.

Include the refresh token and required parameters, and send a POST request. The response is returned in JSON format. The refresh_token is returned only when the validity period of the refresh token is left less than a month, which means that you may not get refresh_token and refresh_token_expires_in in your response.

When you use the SDK for JavaScript, you also need to refresh an access token via REST API due to security policy.

Request

Header

Name	Description	Required
Content-Type	Content-Type: application/x-www-form-urlencoded;charset=utf-8 The data type of the request.	O

Body

Name	Type	Description	Required
grant_type	String	Fixed to refresh_token.	O
client_id	String	REST API key that Kakao issues when you register an app. You can check Your REST API key in [My Application] > [App Keys].	O
refresh_token	String	refresh_token that has been issued in response to the Getting tokens API, which is used to refresh the access and refresh tokens.	O
client_secret	String	An additional code to strengthen security when issuing tokens. You can create a client secret code by clicking [Create code] on the [My Application] > [Kakao Login] > [Security] page. You must add this parameter if 'Client Secret' is activated on this page. Otherwise, the token is not issued from the authorization server.	X

Response

Body

Name	Type	Description	Required
token_type	String	A type of a token, fixed to bearer.	O
access_token	String	A new access token that has been refreshed.	O
expires_in	Integer	Validity period in seconds until the access token expires.	O
refresh_token	String	A new refresh token that has been refreshed. Possible to refresh only when the validity period is left less than a month.	X
refresh_token_expires_in	Integer	Validity period in seconds until the refresh token expires.	X
id_token	String	A new ID Token that has been refreshed. IMPORTANT: Only returned when you integrate Kakao Login with OpenID Connect and request with the refresh token that is issued along with an ID token.	X

Sample

Request

curl -v -X POST "https://kauth.kakao.com/oauth/token" \
    -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
    -d "grant_type=refresh_token" \
    -d "client_id=${REST_API_KEY}" \
    -d "refresh_token=${REFRESH_TOKEN}"

Response: If OAuth request is successful

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "access_token":"${ACCESS_TOKEN}",
    "token_type":"bearer",
    "refresh_token":"${REFRESH_TOKEN}",  //optional
    "refresh_token_expires_in":5184000,  //optional
    "expires_in":43199,
}

Response: If OIDC request is successful

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "token_type":"bearer",
    "access_token":"${ACCESS_TOKEN}",
    "expires_in":43199,
    "refresh_token":"${REFRESH_TOKEN}",  //optional
    "refresh_token_expires_in":5184000,  //optional
    "id_token":"${ID_TOKEN}",
}

Retrieve user information

Basic information

Method	URL	Authorization
GET/POST	https://kapi.kakao.com/v2/user/me	Access token Service app admin key

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

This API enables you to retrieve Kakao Account information of a user who is logged into Kakao. You can request this API with either an access token or an Admin key. You must be careful not to leak your Admin key that has all authorities and use it only when requesting from the server.

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.

Send a GET or POST request by including either the access token or the Admin key in the request header. If you use the Admin key, you should also pass a service user ID.

To retrieve certain user information only, specify the scopes of user information through property_keys.

If the request is successful, the user information is returned in JSON format. The response includes the custom property keys and values added on the User Properties page.

Request: Using access token

Header

Name	Description	Required
Authorization	Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication.	O
Content-Type	Content-Type: application/x-www-form-urlencoded;charset=utf-8 The data type of the request.	O

Body

Name	Type	Description	Required
secure_resource	Boolean	Whether to use HTTPS for the image URL scheme. If true, HTTPS is used. (Default: false)	X
property_keys	String[]	List of property keys you want to retrieve. (Example: ["kakao_account.email","kakao_account.gender"]) See property_keys.	X

property_keys

Name	Description
kakao_account.profile	Whether to own Kakao Account's profile, Nickname, profile image URL, and thumbnail image URL that are set as Kakao Account are reflected in real time.
kakao_account.email	Whether to own Kakao Account's email, email, verification status and validation status of email.
kakao_account.age_range	Whether to own Kakao Account's age range, age range.
kakao_account.birthday	Whether to own Kakao Account's birthday, birthday.
kakao_account.gender	Whether to own Kakao Account's gender, gender.

* Deprecated 'properties.profile_image', 'properties.thumbnail_image', and 'properties.nickname' that are user's profile information saved in a service. Instead, use the profile information under 'kakao_account' passed in the response of Retrieving user information API. Refer to Notice.

Request: Using service app admin key

Header

Name	Description	Required
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication.	O
Content-Type	Content-Type: application/x-www-form-urlencoded;charset=utf-8 The data type of the request.	O

Body

Name	Type	Description	Required
target_id_type	String	A type of a service user ID. Fixed to user_id.	O
target_id	Long	Service user ID.	O
secure_resource	Boolean	Whether to use HTTPS for the image URL scheme. If true, HTTPS is used. (Default: false)	X
property_keys	String[]	List of property keys you want to retrieve. (Example: ["kakao_account.email","kakao_account.gender"]) See property_keys.	X

Response

Body

Name	Type	Description	Required
id	Long	Service user ID.	O
has_signed_up	Boolean	Only returned when the Auto-link setting is disabled. Whether the user is completely linked with (signed up) your app. false: Preregistered true: Registered	X
connected_at	Datetime	The time when the user is linked with a service in UTC*.	X
synched_at	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	JSON	Additional user information saved on the Kakao platform to use it later. Refer to Prerequisites > User properties.	X
kakao_account	KakaoAccount	Kakao Account information.	X
for_partner	Partner	Additional information, including uuid.	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.

KakaoAccount

Name	Type	Description	Required
profile_needs_agreement	Boolean	Whether consent to profile is required. Required user consent: Profile Info(nickname/profile image)	X
profile_nickname_needs_agreement	Boolean	Whether consent to nickname is required. Required user consent: Nickname	X
profile_image_needs_agreement	Boolean	Whether consent to profile image is required. Required user consent: Profile image	X
profile	Profile	Profile information Required user consent: Profile Info(nickname/profile image), Nickname, Profile image	X
email_needs_agreement	Boolean	Whether consent to email is required. Required user consent: Email	X
is_email_valid	Boolean	Whether email address is valid. If the email has expired because it is used for another Kakao Account, false is returned. Required user consent: Email	X
is_email_verified	Boolean	Whether email address is verified. Required user consent: Email	X
email	String	Representative email Required user consent: Email NOTE: Cautions when using email	X
name_needs_agreement	Boolean	Whether consent to name is required. Required consent item: Name	X
name	String	Name of Kakao Account. Required consent item: Name	X
age_range_needs_agreement	Boolean	Whether consent to age range is required. Required user consent: Age range	X
age_range	String	Age range. 1~9, 10~14, 15~19, 20~29, 30~39, 40~49, 50~59, 60~69, 70~79, 80~89, 90~ Required user consent: Age range	X
birthyear_needs_agreement	Boolean	Whether consent to birthyear is required. Required user consent: Birth Year	X
birthyear	String	Birthyear in YYYY format. Required user consent: Birth Year	X
birthday_needs_agreement	Boolean	Whether consent to birthday is required. Required user consent: Birthday	X
birthday	String	Birthday in MMDD format. Required user consent: Birthday	X
birthday_type	String	Solar or Lunar birthday. SOLAR or LUNAR. Required user consent: Birthday	X
gender_needs_agreement	Boolean	Whether consent to gender is required. Required user consent: Gender	X
gender	String	Gender. female or male. Required user consent: Gender	X
phone_number_needs_agreement	Boolean	Whether consent to phone number is required. Required user consent: Phone number	X
phone_number	String	Phone number. For domestic numbers, in +82 00-0000-0000 format. For international numbers, the position of a hyphen(-) or a seperator may differ according to countries. Refer to libphonenumber. Required user consent: Phone number	X
ci_needs_agreement	Boolean	Whether consent to CI for a reference is required. Required user consent: CI(Connecting Information)	X
ci	String	An encoded identifier to check if the same user has already been registered (Connecting Information). Required user consent: CI(Connecting Information)	X
ci_authenticated_at	Datetime	The time when Cerificate Authority issues CI in UTC*. Required user consent: CI(Connecting Information)	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.

* Deprecated 'has_${FIELD_NAME}' that indicates whether the user retains the data. Instead, use '${FIELD_NAME}_needs_agreement' that covers whether the user is required to consent to the scope.

Profile

Name	Type	Description	Required
nickname	String	Nickname. Required user consent: Profile Info(nickname/profile image) or Nickname	X
thumbnail_image_url	String	Profile thumbnail image URL. 110x110 pixels or 100x100 pixels. Required user consent: Profile Info(nickname/profile image) or Profile image	X
profile_image_url	String	Profile image URL. 640x640 pixels or 480x480 pixels. Required user consent: Profile Info(nickname/profile image) or Profile image	X
is_default_image	Boolean	Whether the default image is used for profile image. true: the default profile image is used because a user has not registered any profile image. false: the user's profile image is used. Required user consent: Profile Info(nickname/profile image) or Profile image NOTE: From Tuesday, June 1, 2021, if is_default_image is true, the URL of the default profile image is returned as profile_image_url and thumbnail_image_url. Refer to DevTalk for more details.	X
is_default_nickname	Boolean	Whether the nickname is the default nickname. If the user sets a nickname that does not comply with the operating policies, "Enter your nickname" is applied as the default nickname. true: The default nickname false: Not the default nickname Required user consent: Profile Info(nickname/profile image) or Nickname	X

Partner

Name	Type	Description	Required
uuid	String	User's unique ID Provided when the app has permission to use Kakao Talk Messaging APIs. Required user consent: Send message in KakaoTalk (talk_message)	X

Sample

Request: All information using access token

curl -v -G GET "https://kapi.kakao.com/v2/user/me" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"

Request: Email using access token

curl -v -X POST "https://kapi.kakao.com/v2/user/me" \
    -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    --data-urlencode 'property_keys=["kakao_account.email"]'

Request: Email using admin key

curl -v -X POST "https://kapi.kakao.com/v2/user/me" \
    -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    -d "target_id=123456789" \
    --data-urlencode 'property_keys=["kakao_account.email"]'

Response: Success

HTTP/1.1 200 OK
{
    "id":123456789,
    "connected_at": "2021-09-23T06:08:31Z",
    "kakao_account": { 
        "profile_nickname_needs_agreement": false,
        "profile_image_needs_agreement": false,
        "profile": {
            "nickname": "Ryan",
            "thumbnail_image_url": "http://yyy.kakao.com/.../img_110x110.jpg",
            "profile_image_url": "http://yyy.kakao.com/dn/.../img_640x640.jpg",
            "is_default_image": false,
            "is_default_nickname": false
        },
        "email_needs_agreement": false, 
        "is_email_valid": true,   
        "is_email_verified": true,   
        "email": "sample@sample.com",
        "name_needs_agreement": false,
        "name": "Cool Mike",
        "age_range_needs_agreement": false,
        "age_range": "20~29",
        "birthyear_needs_agreement": false,
        "birthyear": "2002",
        "birthday_needs_agreement": false,
        "birthday_type": "SOLAR",
        "birthday": "1130",
        "gender_needs_agreement": false,
        "gender": "male",
        "phone_number_needs_agreement": false,
        "phone_number": "+82 10-1234-5678",
        "ci_needs_agreement": false,
        "ci": "${CI}",
        "ci_authenticated_at": "2022-05-31T07:50:55Z"
    },
    "properties":{
        "${CUSTOM_PROPERTY_KEY}": "${CUSTOM_PROPERTY_VALUE}",
        ...
    },
    "for_partner": {
        "uuid": "${UUID}"
    }
}

Response: Success, if user consents to 'Nickname' only

HTTP/1.1 200 OK
{
    "id":123456789,
    "kakao_account": { 
        "profile__nickname_needs_agreement": false,
        "profile": {
            "nickname": "Ryan"
        },
    },
    "properties":{
        "${CUSTOM_PROPERTY_KEY}": "${CUSTOM_PROPERTY_VALUE}",
        ...
    }
}

Retrieve shipping address

Basic information

Method	URL	Authorization
GET	https://kapi.kakao.com/v1/user/shipping_address	Access token Service app admin key

Permission	Prerequisite	Kakao Login	User consent
Required	Register platforms Activate Kakao Login Manage consent items	Required	Required: Shipping information

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

You can request a user's shipping address with either an access token or your app's Admin key. For a service administrator, make a request from a server by using the Admin key in the request header, and specify target_id for a service user ID to be retrieved.

If the request is successful, the response includes a list of shipping addresses. 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.

Request: Using access token

Header

Name	Description	Required
Authorization	Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
address_id	Long	If there are multiple shipping addresses, specify an address ID to get a specific shipping address.	X
from_updated_at	Integer	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	Integer	Number of (two or more) shipping addresses displayed on a page. (Default: 10)	X

Request: Using service app admin key

Header

Name	Description	Required
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
target_id_type	String	A type of a service user ID. Fixed to user_id.	O
target_id	Long	Service user ID.	O
address_id	Long	If there are multiple shipping addresses, specify an address ID to get a specific shipping address.	X
from_updated_at	Integer	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	Integer	Number of (two or more) shipping addresses displayed on a page. (Default: 10)	X

Response

Body

Name	Type	Description	Required
user_id	Long	Service user ID.	O
shipping_addresses	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
shipping_addresses_needs_agreement	Boolean	Whether consent to shipping addresses is required.	X

* Deprecated 'has_shipping_addresses' that indicates whether the user retains the shipping addreses. Instead, use '${FIELD_NAME}_needs_agreement' that covers whether the user is required to consent to the scope.

ShippingAddress

Name	Type	Description	Required
id	Long	Shipping address ID.	O
name	String	Shipping address name.	X
is_default	Boolean	Whether the shipping address is a default address or not.	O
updated_at	Integer	The time when a user updated the shipping address.	X
type	String	Shipping address type. OLD (Administrative address) or NEW (Road name address) type of address.	X
base_address	String	Base address that is automatically input when searching for a zipcode.	X
detail_address	String	Detailed address that a user adds to the base address.	X
receiver_name	String	Recipient name.	X
receiver_phone_number1	String	Recipient phone number.	X
receiver_phone_number2	String	Additional recipient phone number.	X
zone_number	String	New type of 5-digit postal code for a road name address system. Required for the road name address system.	X
zip_code	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

Sample

Request: Using access token

curl -v -G GET "https://kapi.kakao.com/v1/user/shipping_address" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"

Request: Using service app admin key

curl -v -G GET "https://kapi.kakao.com/v1/user/shipping_address" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    -d "target_id=${USER_ID}"

Response

HTTP/1.1 200 OK
{
    "user_id": 9876543211234,
    "shipping_addresses": [
        {
            "id": 319,
            "name": "Work",
            "is_default": true,
            "updated_at": 1538448856,
            "type": "NEW",
            "base_address": "경기 성남시 분당구 판교역로 231 (삼평동, 에이치스퀘어 에스동)",
            "detail_address": "6층",
            "receiver_name": "판교",
            "receiver_phone_number1": "031-123-2345",
            "receiver_phone_number2": "",
            "zone_number": "13494",
            "zip_code": "463-400"
        }, {
            "id": 320,
            "name": "Work",
            "is_default": false,
            "updated_at": 1538450389,
            "type": "OLD",
            "base_address": "경기 성남시 분당구 삼평동 680 (삼평동, 에이치스퀘어 에스동)",
            "detail_address": "6층",
            "receiver_name": "판교2",
            "receiver_phone_number1": "010-0056-1234",
            "receiver_phone_number2": "",
            "zone_number": "13494",
            "zip_code": "463-400"
        }
    ],
    "shipping_addresses_needs_agreement": false
}

Store user information

Basic information

Method	URL	Authorization
POST	https://kapi.kakao.com/v1/user/update_profile	Access token

Permission	Prerequisite	Kakao Login	User consent
-	Register platforms Activate Kakao Login Manage user properties	Required	-

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

Send a POST request by passing the access token in the request header. You must pass the custom property keys and values that you want to upadate through properties as data-urlencode parameter. For example, if you want to update a user's clothing size, set properties to {"clothing_size":"small"}.

If the request is successful, the service user ID requested to store information is returned in your response. After storing user information in the property keys, you can retrieve all or some of the saved user information by Retrieving user information.

Request

Header

Name	Description	Required
Authorization	Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication.	O
Content-Type	Content-Type: application/x-www-form-urlencoded;charset=utf-8 The data type of the request.	O

Body

Name	Type	Description	Required
properties	JSON	A list of user information to be stored in {"key":"value"} format. For key, check the property keys in [My Application] > [Kakao Login] > [User Properties]. (Example: {"clothing_size":"small"})	O

Response

Body

Name	Type	Description	Required
id	Long	Service user ID.	O

Sample

Request

curl -v -X POST "https://kapi.kakao.com/v1/user/update_profile" \
    -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    --data-urlencode 'properties={"${CUSTOM_PROPERTY_KEY}":"${CUSTOM_PROPERTY_VALUE}"}'

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id":123456789
}

Retrieve user list

Basic information

Method	URL	Authorization
GET	https://kapi.kakao.com/v1/user/ids	Service app admin key

Permission	Prerequisite	Kakao Login	User consent
-	Register platforms Activate Kakao Login	Required	-

This API is for an app administrator to retrieve a list of information on app users.

Send a GET request by passing your Admin key in the header. You can designate the order and range of service user IDs to be retrieved using the request parameters. The list of service user IDs is returned in JSON format as you request. If all service user IDs are not displayed on a single page, the response includes the URLs for the previous and next page.

Request

Header

Name	Description	Required
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
limit	Integer	Number of users per a page. (Default: 100, Minimum: 1, Maximum: 100)	X
from_id	Long	The service user ID starting the page from. The user list includes from_id and higher service user IDs. Use one of the service user IDs in the response for this parameter. If not specified, the service user ID with the lowest number comes first.	X
order	String	Page search direction. Use either asc or desc. - asc: sort in ascending order. - desc: sort in descending order. (Default: asc)	X

Response

Body

Name	Type	Description	Required
elements	Integer[]	List of service user IDs.	O
total_count	Integer	Total number of app users. Deprecated: No longer available after January 10, 2022.	O
before_url	String	Previous page URL. If there is no previous page, null is returned.	X
after_url	String	Next page URL. If there is no next page, null is returned.	X

* total_count: Deprecated. To check the number of app users, go to [My Application] > [Statistics] > [Users] and see the user activity information. For more information, refer to Notice.

Sample

Request: 100 users from the beginning

curl -v -G GET "https://kapi.kakao.com/v1/user/ids" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}"

Request: 3 users with ID numbers 12345 or higher

curl -v -G GET "https://kapi.kakao.com/v1/user/ids" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d 'limit=3&order=asc' \
    -d 'from_id=12345'

Response

HTTP/1.1 200 OK
{
    "elements": [
        1376016924426111111, 1376016924426222222, 1376016924426333333
    ], 
    "before_url": "http://kapi.kakao.com/v1/user/ids?limit=3&order=desc&from_id=1376016924426111111&app_key=12345674ae6e12379d5921f4417b399e7", 
    "after_url": "http://kapi.kakao.com/v1/user/ids?limit=3&order=asc&from_id=1376016924426333333&app_key=12345674ae6e12379d5921f4417b399e7"
}

Retrieve multiple user information

Basic information

Method	URL	Authorization
GET	https://kapi.kakao.com/v2/app/users	Service app admin key

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

This API is for an app administrator to retrieve the information of multiple app users. You must be careful not to leak your Admin key that has all authorities and use it only when requesting from the server.

Include the app's Admin key in the request header, and send a GET request. Pass the list of users to be retrieved through the target_ids parameter as an array type.

If the request is successful, the list of the requested user information is returned. The user's Service user ID and connected time are included in the response by default.

You can also request additional user information using the property_keys parameter. For this, you must set consent item to retrieve the user information.

Pass the user information to be retrieved and the predefined keys as the value of property_keys with a string array type.

property_keys=["id","has_signed_up","kakao_account.age"]

For the user information with sub-scopes, you can add a dot(.) to the key as the value of property_keys. Then, you can request all sub-scopes under the key.

property_keys=["kakao_account.","properties."]

If you want to request some sub-scopes only, specify the sub-scope's key after the dot (.) and pass it.

property_keys=["kakao_account.email","kakao_account.gender"]

For the inclusive scopes in which related information is included, you can retrieve the related information along with the scope when you request. For example, if you request email information by specifying "kakao_account.email" as the value of property_keys, the related information — kakao_account.email_needs_agreement, kakao_account.is_email_valid, and kakao_account.is_email_verified — are returned along with kakao_account.email.

To request all user information, pass the following values for property_keys.

property_keys=["kakao_account.","properties.","has_signed_up"]

To request all user information of a specific user without specifying any parameters, use the Retrieve user information API.

Request

Header

Name	Description	Required
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication.	O
Content-Type	Content-Type: application/x-www-form-urlencoded;charset=utf-8 The data type of the request.	O

Query parameter

Name	Type	Description	Required
target_ids	Long[]	List of user IDs to be retrieved. You can request information of at most 100 users. If you request user information by specifying property_keys, you can request information of up to 20 users.	O
target_id_type	String	Type of user ID set as target_ids. Fixed to user_id.	O
property_keys	String[]	List of property keys you want to retrieve. To see available property keys, refer to the scope IDs at User information and property keys at User property.	X

Response

Body

Name	Type	Description	Required
elements	UserInfo[]	List of user information. By default, only basic user information such as ID is included in the response of Retrieving multiple user information API . You can request to retrieve more user information using the property_keys parameter. To see available user information, refer to User information.	O

UserInfo

Name	Type	Description
id	Long	Service user ID (user_id).
synched_at	Datetime	The time when the user is logged in through Kakao Sync Simple Signup in UTC*.
connected_at	Datetime	The time when the user is linked with a service in UTC*.
kakao_account	KakaoAccount	Kakao Account information.
properties	JSON	Additional user information saved through the custom property keys on the User Properties page.

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

Sample

Request

curl -v -G GET "https://kapi.kakao.com/v2/app/users" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    --data-urlencode "target_ids=[1399634384,1406264199]" 

Request: Email and profile by specifying property_keys

curl -v -G GET "https://kapi.kakao.com/v2/app/users" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    --data-urlencode "target_ids=[1399634384,1406264199]" \
    --data-urlencode 'property_keys=["kakao_account.email","kakao_account.profile"]'

Request: All available user information

curl -v -G GET "https://kapi.kakao.com/v2/app/users" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    --data-urlencode "target_ids=[1285016924429472463]" \
    --data-urlencode 'property_keys=["kakao_account.","properties.","has_signed_up"]'

Response

HTTP/1.1 200 OK
[
    {
        "id":1406264199,
        "connected_at":"2020-07-14T06:15:36Z",
        // Only returned for the service that applies Kakao Sync. 
        "synched_at":"2020-07-14T06:15:36Z"
    },
    {
        "id":1399634384,
        "connected_at":"2020-07-06T09:55:51Z",
        // Only returned for the service that applies Kakao Sync. 
        "synched_at":"2020-07-06T09:55:51Z"
    }
    ...
]

Response: Email and profile

HTTP/1.1 200 OK
[
    {
        "id":1399634384,
        "connected_at":"2020-07-06T09:55:51Z",
        "kakao_account":{
            "profile_needs_agreement":false,
            "profile":{
                "nickname":"춘식이",
                "thumbnail_image_url":"http://k.kakaocdn.net/dn/zK7QA/btqzpE4aqO1/pl2HpfVBUI9s1SSrstperq/img_110x110.jpg",
                "profile_image_url":"http://k.kakaocdn.net/dn/zK7QA/btqzpE4aqO1/pl2HpfVBUI9s1wqsgrEAVk/img_640x640.jpg",
                "is_default_image":false
            },
            "email_needs_agreement":false,
            "is_email_valid":true,
            "is_email_verified":true,
            "email":"sweetpotato@kakao.com"
        }
    },
    {
        "id":1406264199,
        "connected_at":"2020-07-14T06:15:36Z",
        "kakao_account":{
            "profile_needs_agreement":false,
            "profile":{
                "nickname":"나비",
                "thumbnail_image_url":"http://k.kakaocdn.net/dn/DCjQu/btqti3A2gEc/zgQwddmSnG7CDfmKtTO1/img_110x110.jpg",
                "profile_image_url":"http://k.kakaocdn.net/dn/DCjQu/btqti3A2gEc/zgip1O4JmSnG8sDfmKtTO1/img_640x640.jpg",
                "is_default_image":false
            },
            "email_needs_agreement":true
            }
    }
    ...
]

Response: All available user information

• Refer to the sample response of the Retrieve user information API.

Request additional consent

Basic information

Method	URL	Authorization
GET	https://kauth.kakao.com/oauth/authorize	-

Permission	Prerequisite	Kakao Login	User consent
-	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

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 Concepts > Request additional consent thoroughly for a better understanding.

You can use this API, as an example, for a user who has not agreed to provide a birthday once logging in to the service. When the service needs birthday information to provide a service in the middle of the use of the service, request the information through this API.

To request this API, add the scopes you want to request consent in the scope parameter to the request of the Getting authorization code API. You must configure consent items for the required scopes.

Calling this API presents the Consent screen that includes the requested scope as a consent item. 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.

If the request is successful, you will get a new authorization code when a user consents to the scope. Then, request the Getting tokens API to get new tokens using the newly issued authorization code. After that, you must use the new tokens when you request the Kakao APIs.

Request

Query parameter

Name	Type	Description	Required
client_id	String	REST API key that Kakao issues when you register an app. You can check Your REST API key in [My Application] > [App Keys].	O
redirect_uri	String	URI to get the authorization code.	O
response_type	String	Fixed to code.	O
scope	String	Scope ID of the User information you want to request additional consent. IMPORTANT: If you use OpenID Connect, you must add openid to scope along with the scope values you want to obtain consent. If not, OAuth is applied even though OIDC is enabled. NOTE: You can figure out each scope's ID in [My Application] > [Kakao Login] > [Consent Items]. You can pass multiple scopes by separating by comma(,) without space. (Example: scope=openid,account_email,gender)	O
state	String	Parameter to strengthen security. Random string generated by your app to keep the state between the request and callback. It is recommended to use this parameter to protect from Cross-Site Request Forgery(CSRF).	X
nonce	String	Parameter to strengthen security. To prevent replay attacks, generate random strings and include the request. IMPORTANT: Allowed to set only when you integrate Kakao Login with OpenID Connect.	X

Response

• Same as the response of Getting authorization code API for Kakao Login.

Sample

Request: Additional consent to email and gender using OAuth

https://kauth.kakao.com/oauth/authorize?client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code&scope=account_email,gender

Request: Additional consent to email and gender using OIDC

https://kauth.kakao.com/oauth/authorize?client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code&scope=openid,account_email,gender

Retrieve consent details

Basic information

Method	URL	Authorization
GET	https://kapi.kakao.com/v2/user/scopes	Access token Service app admin key

Permission	Prerequisite	Kakao Login	User consent
-	Register platforms Activate Kakao Login Manage consent items	Required	-

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], check if a user has agreed to each scope and if the scope is revocable. If a user has agreed to a scope before, the scope is included in the response even though your app is currently not using the scope.

For authorization, you can use an access token or your Admin key. Send a GET request with the issued access token or your Admin key in the request header. When requesting with the Admin key, you must pass the service user ID (user_id) of the target user that you want to retrieve.

If the request is successful, the API returns a JSON array of the scopes set in the app. If the user has agreed to a scope, the value of agreed is returned to true.

You can also designate the scopes 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.

Request: Using access token

Header

Name	Description	Required
Authorization	Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
scopes	String[]	Used when you retrieve specific scopes only. List of scope IDs you want to retrieve. You can pass multiple scopes by separating by comma(,).	X

Request: Using service app admin key

Header

Name	Description	Required
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
target_id_type	String	A type of a service user ID. Fixed to user_id.	O
target_id	Long	Service user ID of the user to be retrieved.	O
scopes	String[]	Used when you retrieve specific scopes only. List of scope IDs you want to retrieve. You can pass multiple scopes by separating by comma(,).	X

Response

Body

Name	Type	Description	Required
id	Long	Service user ID.	O
scopes	Scope[]	List of scope information.	O

Scope

Name	Type	Description	Required
id	String	Scope ID.	O
display_name	String	Name or description of the scope (consent item) displayed on the Consent screen.	O
type	String	Scope type. PRIVACY or SERVICE. PRIVACY: scopes for Personal Information SERVICE: scopes for Permission	O
using	Boolean	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	Boolean	Whether the user has agreed to the scope. true: The user has agreed. false: The user has not agreed.	O
revocable	Boolean	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

Sample

Request: Using access token

curl -v -G GET "https://kapi.kakao.com/v2/user/scopes" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"

Request: Retrieving specific scopes only using access token

curl -v -G GET "https://kapi.kakao.com/v2/user/scopes" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    --data-urlencode 'scopes=["account_email","friends"]'

Request: Using service app admin key

curl -v -G GET "https://kapi.kakao.com/v2/user/scopes" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    -d "target_id=123456789" 

Response: Success

HTTP/1.1 200 OK
{
    "id":123456789,
    "scopes":[
        {
            "id":"profile",
            "display_name":"Profile Info(nickname/profile image)",
            "type":"PRIVACY",
            "using":true,           // Whether your app is using this scope or not
            "agreed":true,          // Whether the user has agreed to this scope or not
            "revocable":false       // Whether you can revoke this scope or not
        },
        {
            "id":"account_email",
            "display_name":"Email",
            "type":"PRIVACY",
            "using":true,           // Whether your app is using this scope or not
            "agreed":true,          // Whether the user has agreed to this scope or not
            "revocable":true        // Whether you can revoke this scope or not
        },
        {
            "id":"shipping_address",
            "display_name":"Shipping information (receiver, shipping address, phone number)",
            "type":"PRIVACY",
            "using":true,           // Whether your app is using this scope or not
            "agreed":false         // Whether the user has agreed to this scope or not
        },
        ...
    ]
}

Response: Consent details of Email and Friends List in Kakao Service

HTTP/1.1 200 OK
{
    "id":123456789,
    "scopes":
    [
        {
            "id":"friends",
            "display_name":"Friends List in Kakao Service(Including profile image, nickname, and favorites)",
            "type":"PRIVACY",
            "using":true,
            "agreed":true,
            "revocable":false
        },
        {
            "id":"account_email",
            "display_name":"Email",
            "type":"PRIVACY",
            "using":true,
            "agreed":false
        }
    ]
}

Revoke consent

Basic information

Method	URL	Authorization
POST	https://kapi.kakao.com/v2/user/revoke/scopes	Access token Service app admin key

Permission	Prerequisite	Kakao Login	User consent
-	Register platforms Activate Kakao Login Manage consent items	Required	-

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.

For authorization, you can use an access token or your Admin key. Include the issued access token or your Admin key in the request header, and send a POST request with the list of scopes that you want to revoke. When requesting with the Admin key, you must pass the service user ID (user_id) of the target user.

If the request is successful, the API returns a list of the consent items (scopes) that the changes are applied. The response includes the information about if your app is using the scope, if the user has agreed to the scope, or if the scope is revocable. If the requested scope is successfully revoked, the value of agreed is returned to false.

Request: Using access token

Name	Description	Required
Authorization	Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication.	O

Body

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

Request: Using service app admin key

Header

Name	Description	Required
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication.	O

Body

Name	Type	Description	Required
target_id_type	String	A type of a service user ID. Fixed to user_id.	O
target_id	Long	Service user ID of a taget user.	O
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.	O

Response

• Same as the response of Retrieving consent details API.

Sample

Request: Using access token

curl -v -X POST "https://kapi.kakao.com/v2/user/revoke/scopes" \
    -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    --data-urlencode 'scopes=["account_email"]'

Request: Using service app admin key

curl -v -X POST "https://kapi.kakao.com/v2/user/revoke/scopes" \
    -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    -d "target_id=123456789" \
    --data-urlencode 'scopes=["account_email"]'

Response: Success, if consent to Email is rovoked

HTTP/1.1 200 OK
{
    "id":123456789,
    "scopes":[
        {
            "id":"profile",
            "display_name":"Profile Info(nickname/profile image)",
            "type":"PRIVACY",
            "using":true,
            "agreed":true,
            "revocable":false
        },
        {
            "id":"friends",
            "display_name":"Friends List in Kakao Service(Including profile image, nickname, and favorites)",
            "type":"PRIVACY",
            "using":true,
            "agreed":true,
            "revocable":false
        },
        {
            "id":"account_email",
            "display_name":"Email",
            "type":"PRIVACY",
            "using":true,
            "agreed":false          //Changed to 'false' if the consent is successfully revoked
        },
        {
            "id":"talk_chats",
            "display_name":"Read chat lists in KakaoTalk",
            "type":"SERVICE",
            "using":true,
            "agreed":true,
            "revocable":false
        },
        ...
    ]
}

Response: Fail, if requesting to revoke 'Required consent item'

HTTP/1.1 403 Forbidden
{
    "msg":"[profile] is not revocable. check out if it's set as required on developers.kakao.com",
    "code":-3
}

Response: Fail, if the requested scope ID is wrong

HTTP/1.1 400 Bad Request
{
    "msg":"There is no scopes to revoke. check out if given scope id([email]) is correct again.",
    "code":-2
}

Get consent to desired service terms

Basic information

Method	URL	Authorization
GET	https://kauth.kakao.com/oauth/authorize	-

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

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 use this API, pass the tags of the terms needed to get consent through service_terms parameter when requesting authorization code. You can check each service term's tag in 'Term's TAG' on the Simple Signup page where you registered the service terms. For multiple tags, separate the service terms by comma(,).

If the Consent screen is not prompted even after calling this API, refer to FAQ.

Request

Query parameter

Name	Type	Description	Required
client_id	String	REST API key that Kakao issues when you register an app. You can check Your REST API key in [My Application] > [App Keys].	O
redirect_uri	String	URI to get the authorization code.	O
response_type	String	Fixed to code.	O
service_terms	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
scope	String	Used to request additional consent.	X
state	String	Parameter to strengthen security. Random string generated by your app to keep the state between the request and callback. It is recommended to use this parameter to protect from Cross-Site Request Forgery(CSRF).	X
nonce	String	Parameter to strengthen security. To prevent replay attacks, generate random strings and include the request. IMPORTANT: Allowed to set only when you integrate Kakao Login with OpenID Connect.	X

Response

• The response is the same as the Getting authorization code. If successful, the Consent screen that only includes the designated service terms is prompted during the login process.

Sample

Request

https://kauth.kakao.com/oauth/authorize?client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code&service_terms=tag1,tag2

Response

HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?code=${AUTHORIZATION_CODE}

Service terms

Retrieve consent details for service terms

Basic information

Method	URL	Authorization
GET	https://kapi.kakao.com/v2/user/service_terms	Access token Service app admin key

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

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

Request as a GET method with the desired authentication information in the header. To get the full service terms list set of an app, request with result as app_service_terms. To get only specific service terms information, request with tags as the tag for that service terms.

If an administrator wants to retrieve a specific user's service terms consent, request with an Admin key on the server. The Admin key should only be used on the server. When using the Admin key, specify what to look up by passing the service user ID in target_id, and pass target_id_type as user_id.

If the request is successful, the response is a JSON object containing the service user ID and service terms list. If the user unlinks from the app, and then logs in, they will go through the consent process again via the Simple Signup screen. This will update the information about the time they agreed to the service terms.

Request: Using access token

Header

Name	Description	Required
Authorization	Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication.	O

Query parameter

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, refer to Example.	X

Request: Using service app admin key

Header

Name	Description	Required
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication.	O

Query parameter

Name	Type	Description	Required
target_id_type	String	A type of a service user ID. Fixed to user_id	O
target_id	Long	Service user ID.	O
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, refer to Example.	X

Response

Body

Name	Type	Description	Required
id	Long	Service user ID.	O
service_terms	ServiceTerms[]	List of service terms.	X

ServiceTerms

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: Agreed false: Disagreed	O
revocable	Boolean	Whether consent is revocable in the service terms. true: Can be revoked false: Cannot be revoked, is in a disagreed state or is a required Term of Service Note: Only service terms with revocable consent are available for Revoke consent for service terms API requests.	O
agreed_at	Datetime	The last time user agreed to the service terms. (RFC3339 internet date/time format)	X
agreed_by	String	Path through which the service terms were agreed to. KAUTH: Consent screen of Kakao Sync Simple Signup. KAPI: Set consent to service terms API.	X

Sample

Request: Using access token, service terms the user has agreed to

curl -v -G GET "https://kapi.kakao.com/v2/user/service_terms" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"

Request: Using access token, list of service terms enabled for an app

curl -v -G GET "https://kapi.kakao.com/v2/user/service_terms" \
    -H 'Authorization: Bearer ${ACCESS_TOKEN}' \
    -d "result=app_service_terms"

Request: Using app admin key, service terms for a specific tag

curl -v -G GET "https://kapi.kakao.com/v2/user/service_terms" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    -d "target_id=${USER_ID}" \
    -d "tags=optional_no_consent,service_2020_0218"

Response: Service terms the user has agreed to

{
    "id": 111111,
    "service_terms": [
        {
            "tag": "optional_20200616",
            "required": false,
            "agreed": true,
            "revocable": true,
            "agreed_at": "2023-06-29T07:39:56Z",
            "agreed_by": "KAUTH"
        },
        {
            "tag": "service_2020_0218",
            "required": true,
            "agreed": true,
            "revocable": false,
            "agreed_at": "2023-06-29T07:39:56Z",
            "agreed_by": "KAUTH"
        },
        ...
    ]
}

Response: Service terms list enabled for an app

{
    "id": 111111,
    "service_terms": [
        {
            "tag": "optional_20200616",
            "required": false,
            "agreed": true,
            "revocable": true,
            "agreed_at": "2023-06-29T07:39:56Z",
            "agreed_by": "KAUTH"
        },
        {
            "tag": "optional_no_consent",
            "required": false,
            "agreed": false,
            "revocable": true
        },
        {
            "tag": "service_2020_0218",
            "required": true,
            "agreed": true,
            "revocable": false,
            "agreed_at": "2023-06-29T07:39:56Z",
            "agreed_by": "KAUTH"
        },
        ...
    ]
}

Response: Service terms for a specific tag

{
    "id": 111111,
    "service_terms": [
        {
            "tag": "optional_no_consent",
            "required": false,
            "agreed": false,
            "revocable": true
        },
        {
            "tag": "service_2020_0218",
            "required": true,
            "agreed": true,
            "revocable": false,
            "agreed_at": "2023-06-29T07:39:56Z",
            "agreed_by": "KAUTH"
        }
    ]
}

Response: Failed, non-existent service terms tags

HTTP/1.1 400 Bad Request
{
    "msg": "There is no tags to get service terms. check out to configured this tags([test]) in app(docu_test).",
    "code": -2
}

Revoke consent for service terms

Basic information

Method	URL	Authorization
POST	https://kapi.kakao.com/v2/user/revoke/service_terms	Access token Service app admin key

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

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.

Request as a POST method with the desired authentication information in the header. Specify the tags of the service terms you want to revoke consent for in tags.

If an administrator wants to revoke a specific user's service terms consent, request with an Admin key on the server. The Admin key should only be used on the server. When using the Admin key, specify what to look up by passing the service user ID in target_id, and pass target_id_type as user_id.

If the request is successful, the response is a JSON object containing a list of revoked service terms. User non-consent or required service terms that cannot be revoked are not included.

Request: Using access token

Header

Name	Description	Required
Authorization	Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication.	O

Body

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

Request: Using service app admin key

Header

Name	Description	Required
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication.	O

Body

Name	Type	Description	Required
target_id_type	String	A type of a service user ID. Fixed to user_id	O
target_id	Long	Service user ID.	O
tags	String	Service terms tags to revoke, limited in the list specified by result. 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

Response

Body

Name	Type	Description	Required
id	Long	Service user ID.	O
revoked_service_terms	RevokedServiceTerms[]	List of revoked service terms Note: User non-consent or required service terms that cannot be revoked are not included.	X

RevokedServiceTerms

Name	Type	Description	Required
tag	String	Tag of revoked service terms	O
agreed	Boolean	The consent status of the service terms after revocation. true: Agreed false: Disagreed	O

Example

Request: Using access token

curl -v -X POST "https://kapi.kakao.com/v2/user/revoke/service_terms" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"
    -d "tags=optional_20200616,optional_no_consent"

Request: Using app admin key

curl -v -X POST "https://kapi.kakao.com/v2/user/revoke/service_terms" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    -d "target_id=${USER_ID}" \
    -d "tags=optional_20200616,optional_no_consent"

Response

{
    "id": 111111,
    "revoked_service_terms": [
        {
            "tag": "optional_20200616",
            "agreed": false
        },
        {
            "tag": "optional_no_consent",
            "agreed": false
        }
    ]
}

Response: Failed, non-existent service terms tags

HTTP/1.1 400 Bad Request
{
    "msg": "There is no tags to revoke. check out to configured this tags([test_tag]) in app(test_app).",
    "code": -2
}

Advanced: Set consent to service terms

Basic information

Method	URL	Authorization
POST	https://kapi.kakao.com/v2/user/upgrade/service_terms	Access token Service app admin key

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

This API set the user consent to specific service terms in the Kakao Sync service. This API does not provide the ability to request consent from users through the KakaoSync Simple Signup Consent screen. It is used by the service to reflect the service terms consent history to the Kakao API platform.

Request as a GET method with the desired authentication information in the header. Specify the tags of the service terms you want to makes the user agree to in tags.

If the request is successful, the response is a JSON object containing a user ID, agreed service terms. A service terms that the user has already agreed to or cannot agree to because the terms tag is invalid are not included.

Cautions

User consent to the service terms must be managed directly by the service. For the service terms that are not agreed, we recommend to get consent by the service own consent process. For required service terms, you can get user consent by Get consent to desired service terms. Refer to Caution on service terms.

Request: Using access token

Header

Name	Description	Required
Authorization	Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication.	O

Body

Name	Type	Description	Required
tags	String	Service terms tags to set consent. Pass multiple tags as a single comma (,) separated string, refer to Example.	O

Request: Using service app admin key

Header

Name	Description	Required
Authorization	Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication.	O

Body

Name	Type	Description	Required
target_id_type	String	A type of a service user ID. Fixed to user_id	O
target_id	Long	Service user ID.	O
tags	String	Service terms tags to set consent, limited in the list specified by result. Pass multiple tags as a single comma (,) separated string, refer to Example.	O

Response

Body

Name	Type	Description	Required
id	Long	Service user ID.	O
agreed_service_terms	AgreedServiceTerms[]	List of service terms that successfully set consent.	X

AgreedServiceTerms

Name	Type	Description	Required
tag	String	Tag of agreed service terms	O
agreed	Boolean	The consent status of the service terms after revocation. true: Agreed false: Disagreed	O
agreed_at	Datetime	The last time user agreed to the service terms. (RFC3339 internet date/time format)	X
agreed_by	String	Path through which the service terms were agreed to. KAUTH: Consent screen of Kakao Sync Simple Signup. KAPI: Set consent to service terms API.	X

Sample

Request: Using access token

curl -v -X POST "https://kapi.kakao.com/v2/internal/user/upgrade/service_terms" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    -d "tags=term01,term02,term03"

Request: Using app admin key

curl -v -X POST "https://kapi.kakao.com/v2/internal/user/upgrade/service_terms" \
    -H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
    -d "target_id=${USER_ID}" \
    -d "target_id_type=user_id" \
    -d "tags=term01,term02,term03"

Response: Service terms the user has agreed to

HTTP/1.1 200 OK
{
    "id": 1376016924429759243,
    "agreed_service_terms": [
        {
            "tag": "term03",
            "agreed": true,
            "agreed_at": "2023-08-02T08:33:25Z",
            "agreed_by": "KAPI"
        }, {
            "tag": "term01",
            "agreed": true,
            "agreed_at": "2023-08-02T08:33:25Z",
            "agreed_by": "KAUTH"
        }, {
            "tag": "term02",
            "agreed": true,
            "agreed_at": "2023-08-02T08:33:25Z",
            "agreed_by": "KAUTH"
        }
    ]
}

Response: Included only some service terms that successfully set consent

HTTP/1.1 200 OK
{
    "id": 1376016924429759243,
    "agreed_service_terms": [
        {
            "tag": "term02",
            "agreed": true,
            "agreed_at": "2023-08-02T08:34:56Z"
        }
    ]
}

Advanced: Login with OpenID Connect

OpenID Connect (OIDC) is an extended version added to the top of the OAuth protocol, used to authenticate users.

What you must do

If you want to integrate Kakao Login with OIDC, you need to get an ID Token as follows:

0. Activate OIDC in [My Application] > [Kakao Login].
1. Get authorization code.
2. Get tokens.

What you can do

After you get an ID token, you can:

• Retrieve Discovery document that you may need while implementing OIDC.
• Retrieve user information for OIDC.
• Decode the ID token, which is intended for debugging only, by calling the Getting ID token information API.

Get public key

Basic information

Method	URL	Authorization
GET	https://kauth.kakao.com/.well-known/jwks.json	-

Permission	Prerequisite	Kakao Login	User consent
-	-	-	-

This API enables you to get the public key that the Kakao authorization server used to sign the ID token. You can use this API to verify ID token.

Send a request to the JSON Web Key Set (JWKS) endpoint of the Kakao authorization server.

Because the public keys change periodically to strengthen security, you must cache the public keys and use them in your service. Note that if you send too many requests, the requests may be blocked.

Response

Body

Name	Type	Description	Required
keys	JWK[]	Array of JSON Web Keys. Refer to JSON Web Key (RFC 7517).	O

JWK

Name	Type	Description	Required
kid	String	Public key ID.	O
kty	String	Type of public key. Fixed to RSA.	O
alg	String	Algorithm intended for use with the key. Fixed to RS256.	O
use	String	Intended use of the public key. Fixed to sig (signature).	O
n	String	Modulus value for public key.	O
e	String	Exponent value for public key.	O

Sample

Request

curl -v -G GET "https://kauth.kakao.com/.well-known/jwks.json"

Response

• This is a sample of jwk.json you can refer to.

HTTP/1.1 200 OK
{
    "keys":[
        {
            "kid":"3f96980381e451efad0d2ddd30e3d3",
            "kty":"RSA",
            "alg":"RS256",
            "use":"sig",
            "n":"q8zZ0b_MNaLd6Ny8wd4cjFomilLfFIZcmhNSc1ttx_oQdJJZt5CDHB8WWwPGBUDUyY8AmfglS9Y1qA0_fxxs-ZUWdt45jSbUxghKNYgEwSutfM5sROh3srm5TiLW4YfOvKytGW1r9TQEdLe98ork8-rNRYPybRI3SKoqpci1m1QOcvUg4xEYRvbZIWku24DNMSeheytKUz6Ni4kKOVkzfGN11rUj1IrlRR-LNA9V9ZYmeoywy3k066rD5TaZHor5bM5gIzt1B4FmUuFITpXKGQZS5Hn_Ck8Bgc8kLWGAU8TzmOzLeROosqKE0eZJ4ESLMImTb2XSEZuN1wFyL0VtJw",
            "e":"AQAB"
        },
        {
            "kid":"9f252dadd5f233f93d2fa528d12fea",
            "kty":"RSA",
            "alg":"RS256",
            "use":"sig",
            "n":"qGWf6RVzV2pM8YqJ6by5exoixIlTvdXDfYj2v7E6xkoYmesAjp_1IYL7rzhpUYqIkWX0P4wOwAsg-Ud8PcMHggfwUNPOcqgSk1hAIHr63zSlG8xatQb17q9LrWny2HWkUVEU30PxxHsLcuzmfhbRx8kOrNfJEirIuqSyWF_OBHeEgBgYjydd_c8vPo7IiH-pijZn4ZouPsEg7wtdIX3-0ZcXXDbFkaDaqClfqmVCLNBhg3DKYDQOoyWXrpFKUXUFuk2FTCqWaQJ0GniO4p_ppkYIf4zhlwUYfXZEhm8cBo6H2EgukntDbTgnoha8kNunTPekxWTDhE5wGAt6YpT4Yw",
            "e":"AQAB"
        }
    ]
}

Retrieve Discovery document

Basic information

Method	URL	Authorization
GET	https://kauth.kakao.com/.well-known/openid-configuration	-

Permission	Prerequisite	Kakao Login	User consent
-	-	-	-

This API enables you to retrieve the metadata required while implementing OIDC. When you implement OIDC, you may need multiple endpoints to authenticate users, request user information, or get tokens. Thus, we provide the Discovery document that contains metadata such as the URIs of the authorization, token, user information, and JWK endpoints, and the detailed configuration for authorization. To see the full specifications, refer to 3. OpenID Provider Metadata at the OpenID Connect Discovery 1.0.

Response

Body

Name	Type	Description	Required
issuer	String	Issuer identifier. Only https://kauth.kakao.com is returned.	O
authorization_endpoint	String	URL of the OAuth 2.0 authorization endpoint.	O
token_endpoint	String	URL of the token management endpoint for getting token or refreshing token.	O
userinfo_endpoint	String	URL of the user information endpoint.	O
jwks_uri	String	URL of the JSON Web Key (RFC 7517) document.	O
token_endpoint_auth_methods_supported	String[]	A list of client authentication methods supported to Getting token API. client_secret_post: Send Client Secret in POST method.	O
subject_types_supported	String[]	Subject Identifier types. Only public is returned.	O
id_token_signing_alg_values_supported	String[]	JWS signing algorithm. Only RS256 is returned.	O
request_uri_parameter_supported	Boolean	Whether Pushed Authorization is supported. Only false(Not support) is returned.	O
response_types_supported	String[]	Value of response_type used for OAuth 2.0 authorization. Only code is returned.	O
response_modes_supported	String[]	A list of response modes supported to Getting authorization code API. query: Query string	O
grant_types_supported	String[]	List of the supported OAuth 2.0 Grant Type values.	X
code_challenge_methods_supported	String[]	Method used to encode the code_verifier parameter for Proof Key for Code Exchange (PKCE). Only S256 is returned.	O
claims_supported	String[]	List of the claims included in the ID token. For the claim names, refer to Payload of ID token or the response of Getting ID token information API.	O

Sample

Request

curl -v -G GET "https://kauth.kakao.com/.well-known/openid-configuration"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
    "issuer": "https://kauth.kakao.com",
    "authorization_endpoint": "https://kauth.kakao.com/oauth/authorize",
    "token_endpoint": "https://kauth.kakao.com/oauth/token",
    "userinfo_endpoint": "https://kapi.kakao.com/v1/oidc/userinfo",
    "jwks_uri": "https://kauth.kakao.com/.well-known/jwks.json",
    "token_endpoint_auth_methods_supported": ["client_secret_post"],
    "subject_types_supported": ["public"],
    "id_token_signing_alg_values_supported": ["RS256"],
    "request_uri_parameter_supported": false,
    "response_types_supported": ["code"],
    "response_modes_supported": ["query"],
    "grant_types_supported": [
        "authorization_code", "refresh_token"
    ],
    "code_challenge_methods_supported": ["S256"],
    "claims_supported": [
        "iss",
        "aud",
        "sub",
        "auth_time",
        "exp",
        "iat",
        "nonce",
        "nickname",
        "picture",
        "email"
    ]
}

Retrieve user information for OIDC

Basic information

Method	URL	Authorization
GET	https://kapi.kakao.com/v1/oidc/userinfo	Access token

Permission	Prerequisite	Kakao Login	User consent
-	Register platforms Activate Kakao Login Manage consent items Advanced: Activate OpenID Connect	Required	Required: All consent items to request user information

This API provides the standard Claims, which enables you to retrieve the information of the user who is currently logged in. This API only provides the least information for data mapping. If you want to retrieve futher user information, use the Retrieving user information API.

Because this API is provided exclusively for OIDC, you must enable OIDC in [My Application] > [Kakao Login]. Refer to What you must do before using this API.

To use user information included in the ID token, such as nickname, profile thumbnail image, and email, you must call one of the following APIs for the users who log in with Kakao for the first time. If not, the user may unlink from your app because the user is not completely signed up. For more details, refer to Notice.

• Retrieving user information for OIDC (/v1/oidc/userinfo)
• Retrieving user information (/v2/user/me)
• Retrieving Kakao Talk profile (/v1/api/talk/profile)

Send a GET request with the access token issued through the Getting tokens. If the request is successful, the user information is returned in JSON format.

Request

Header

Name	Description	Required
Authorization	Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication.	O

Response

• If Kakao does not retain the user information among the data below, the corresponding key is excluded from the response.

Body

Name	Type	Description	Required
sub	String	Service user ID.	O
name	String	Name of Kakao Account. Required consent item: Name	X
nickname	String	User nickname used in your service. Required user consent: Profile Info(nickname/profile image) or Nickname	X
picture	String	URL of the profile thumbnail image used in your service. Kakao Account thumbnail image is set by default. Required user consent: Profile Info(nickname/profile image) or Profile image	X
email	String	Email address saved in Kakao Account. Required user consent: Email NOTE: Cautions when using email	X
email_verified	Boolean	Whether the email is verified and valid. - true: the email is verified and valid. - false: the email has not been verified or expires because the email is used for another Kakao Account. Required user consent: Email	X
gender	String	Gender. FEMALE or MALE. Required user consent: Gender	X
birthdate	String	Birthdate. Required user consent: Birthday, Birthyear NOTE: Depending on the agreed scopes, the format is different. If a user consents to birthyear only, YYYY format. If a user consents to birthday only, 0000-MM-DD format. If a user consents to both birthyear and birthday, YYYY-MM-DD format.	X
phone_number	String	Phone number. For domestic numbers, in +82 00 0000 0000 or +82 00-0000-0000 format. For international numbers, the position of a hyphen(-) or a seperator may differ according to countries. Refer to libphonenumber. Required user consent: Phone number	X
phone_number_verified	Boolean	Whether the phone number is verified. If phone number is saved, true is returned. Required user consent: Phone number	X

Sample

Request

curl -v -G GET "https://kapi.kakao.com/v1/oidc/userinfo" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"

Response: Success

HTTP/ 1.1 200 OK
{
    "sub": "123456789",
    "name": "Mike",
    "nickname": "Ryan",
    "picture": "http://sample.com/xxx/yyy/img_110x110.jpg",
    "email": "sample@sample.com",
    "email_verified": true,
    "gender": "MALE",
    "birthdate": "2002-11-30",
    "phone_number": "+82 00-1234-5678",
    "phone_number_verified": true
}

Response: Fail

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"
{
    "msg":"this access token does not exist",
    "code":-401
}

Get ID token information

Basic information

Method	URL	Authorization
POST	https://kauth.kakao.com/oauth/tokeninfo	-

Permission	Prerequisite	Kakao Login	User consent
-	Register platforms Activate Kakao Login Manage consent items Advanced: Activate OpenID Connect	Required	-

This API enables you to check the payload information of the issued ID token.

Send a POST request with the id_token issued through the Getting tokens. If the request is successful, ID token information is decoded in JSON format. If failed, refer to Troubleshooting.

Request

Header

Name	Description	Required
Content-Type	Content-Type: application/x-www-form-urlencoded;charset=utf-8 The data type of the request.	O

Body

Name	Description	Required
id_token	ID token that you want to decode.	X

Response

Body

Name	Type	Description	Required
iss	String	Issuer Identifier. Fixed to https://kauth.kakao.com.	O
aud	String	App key of the app which the ID token is issued for. App key passed when you request authorization code through the client_id parameter. If you get an ID token through the Kakao SDK, the app key used to initialize the corresponding SDK is returned.	O
sub	String	Service user ID.	O
iat	Integer	Time when the JWT was issued in Unix time.	O
exp	Integer	Validity period in seconds in Unix time. Same as the validity period of the access token.	O
auth_time	Integer	Time when a user was authenticated in Unix time.	O
nonce	String	Returned if nonce is included in the request of the Getting authorization code API. This value must exactly match the original nonce passed in the request from your app.	X
nickname	String	Nickname saved in Kakao Account. Required user consent: Profile Info(nickname/profile image) or Nickname	X
picture	String	URL of profile thumbnail image saved in Kakao Account. 110x110 pixels or 100x100 pixels. Required user consent: Profile Info(nickname/profile image) or Profile image	X
email	String	Email saved in Kakao Account. Only returned is_email_valid is true. Required user consent: Email NOTE: Cautions when using email	X

Sample

Request

curl -v -X POST "https://kauth.kakao.com/oauth/tokeninfo" \
     -d "id_token=${ISSUED_ID_TOKEN}"

Response: Success

HTTP/1.1 200 OK
{
  "iss":"https://kauth.kakao.com",
  "aud":"${YOUR_APP_KEY}",
  "sub":"42924",
  "iat":1644833352,
  "exp":1644840552,
  "auth_time":1644833336,
  "nonce":"${NONCE}",
  "nickname": "Ryan",
  "picture": "http://sample.com/xxx/yyy/img_110x110.jpg",
  "email": "sample@sample.com"
}

Response: Invalid ID token

HTTP/1.1 400 Bad Request 
{
  "error": "invalid_token",
  "error_description": "invalid id_token format",
  "error_code": "KOE400"
}

Advanced: Manual signup

Basic information

Method	URL	Authorization
POST	https://kapi.kakao.com/v1/user/signup	Access token

Permission	Prerequisite	Kakao Login	User consent
Required	Register platforms Activate Kakao Login	Required	-

The Manual signup API manually links a user with your app to complete signup when the Auto-link is disabled. The Auto-link feature allows you to link a user with your app automatically, which is set by default. To manually link users with your app, you need a separate negotiation with Kakao.

Here are some cases that you must link users with your app manually:

• If a signup is not completed after a user consents to the use of service when logging in.
  • If a user is signed up through a separate verification process or by inputting additional information after logging in.
  • If a user is not signed up immediately until the service approves the signup request.
• If a service needs to manage users' linked status internally.

The service with the Auto-link option disabled must call the Manual signup API to link the service app with a user. You must check if users' signed-up status coincides with the linked status, and then complete signup by calling the Manual signup API. Thus, we highly recommend enabling the Auto-link option except for inevitable cases.

Send a POST request by including the access token in the request header. When you request the Manual signup API, you can also request to store user properties. Even after the link, you can also store user properties through the Storing user information API. When a user is unlinked, the user properties are deleted.

User data provided according to user's linked status

If a user is in a preregistered status, which means the user has not completely signed up through the Manual signup API, only some of the following user information are provided through the Retrieve user information and Retrieve multiple user information.

Name	Key
Service User ID	id
User's unique ID	for_partner.uuid
Profile information (Nickname, Profile image)	kakao_account.profile
Checking if the user is linked	has_signed_up
Time when the user is linked	connected_at
Kakao Account (email)	kakao_account.email
Checking if email is valid	is_email_valid
Checking if email is verified	is_email_verified

Request

Header

Name	Description	Required
Authorization	Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication.	O
Content-Type	Content-Type: application/x-www-form-urlencoded;charset=utf-8 The data type of the request.	O

Body

Name	Type	Description	Required
properties	JSON	A list of user information in {"key":"value"} format. Used when you want to store user information when linking a user. Refer to Manage user properties and Store user information.	X

Response

Body

Name	Type	Description	Required
id	Long	Service user ID that is linked to your app.	O

Sample

Request: Link without updating user properties

curl -v -X POST "https://kapi.kakao.com/v1/user/signup" \
    -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}"

Request: Link and update user properties

curl -v -X POST "https://kapi.kakao.com/v1/user/signup" \
    -H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    --data-urlencode 'properties={"${CUSTOM_PROPERTY_KEY}":"${CUSTOM_PROPERTY_VALUE}"}'

Response: Success

HTTP/1.1 200 OK
{
    "id":1376016924429759228
}

Response: Fail, if user is already linked with app

HTTP/1.1 400 Bad Request
{
    "msg":"already registered",
    "code":-102
}

Response: Fail, if invalid access tokent is used in request

HTTP/1.1 401 Unauthorized
{
    "msg":"this access token does not exist",
    "code":-401
}

Response: Fail, if unregistered property key is used in request

HTTP/1.1 400 Bad Request
{
    "msg":"user property not found ([gender, age] for appId={APP_ID})",
    "code":-201
}

See more

• Reference for REST API