페이지 이동경로
  • Docs>
  • Kakao Login>
  • REST API

Kakao Login

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

For a Kakao Login button, you can download the resources provided by Kakao or customize buttons according to your service user interface by referring to the Design Guide.

Before you begin

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.

Process of OAuth authorization
  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.
Reference

If you want to implement the authentication function with Kakao Login in your service, you can use OpenID Connect.

If you want users to log in through Kakao Talk simply on mobile web environment without inputting their Kakao Account ID and password, you can use the Simple Login function.

Get authorization code

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

URL
GET /oauth/authorize?client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code HTTP/1.1
Host: kauth.kakao.com
Parameter
Name Type Description Required
client_id String REST API key that Kakao issues when you create 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 as 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.
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

To comply with the OAuth 2.0 standard, the 'auth_type' parameter, used to request reauthentication for a user in a logged-in state to enhance security, has been replaced by the 'prompt' parameter. To request reauthentication for a logged-in user, pass "prompt=login" instead of "auth_type=reauthenticate".

Response

Name Type Description Required
code String Authorization code that is used to get an access token. O
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

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.

Session lifetime after authentication with Kakao Account

After an user logs in with a kakao Account, the login session lasts for 24 hours by default. The session lifetime does not change after the initial authorization. If an user chooses to keep the login status, the authorization session is valid for a month.

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

URL
POST /oauth/token HTTP/1.1
Host: kauth.kakao.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
Parameter
Name Type Description Required
grant_type String Fixed as authorization_code. O
client_id String REST API key that Kakao issues when you create 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] > [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

Name Type Description Required
token_type String A type of a token. Fixed as 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" \
 -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":25184000,
    "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":25184000,
    "scope":"openid account_email profile",
    "id_token":"eyJraWQiOiJlYTVkMjU1ZjM0OTIxZDRhNmNhMTBmNmNhZGYyNzAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIyMDU3OTciLCJzdWIiOiI0MjkyNCIsImF1dGhfdGltZSI6MTY0NDgzMjc2NywiaXNzIjoiaHR0cHM6Ly9rYXV0aC5rYWthby5jb20iLCJleHAiOjE2NDQ4Mzk5NjcsImlhdCI6MTY0NDgzMjc2N30.JnDqYsJGnsNwS2xTmWQwUGvvmjbl6hs_EaKgMjVZkCwpSafIBkUHvS9Q1ZNwa9HltrybxoQzSH_GDi1419ZmXcFFQ4RYJ9N-bs4pi65GaczDkU5qDIByKnPjbMRTaEKXsR_zJ5lZEkenYqK-AnhAh5P1empMsndM8vDS9e4a_Fp45YUUEEt0Bumpk_-WtPJVCtjHVvuc6tePxgEJohLkgL1Km2sjjgpPi2UhByCWwWUzvCeY-FQp6fal3w5dddTW5tijfLTHUm9QiY1gAp0xQZcDH4TK6a5NzMLpJ_5A96sSzVlB4y-juhAB0I_TIwS1NkmpwWooa0KjSNanWaOc9g"
}

Auto-login from Kakao Talk

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

URL
GET /oauth/authorize?client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code&prompt=none HTTP/1.1
Host: kauth.kakao.com
Parameter
Name Type Description Required
client_id String REST API key that Kakao issues when you create 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 as 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

Name Type Description Required
code String authorization_code that returns if your request succeeds. O
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

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

URL
POST /v1/user/logout HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer ${ACCESS_TOKEN}
O

Request: Using admin key

URL
POST /v1/user/logout HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK ${APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
target_id_type String A type of a service user ID.
Fixed as user_id.
O
target_id Long Service user ID to be logged out of the service. O

Response

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" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
Request: Using admin key
curl -v -X POST "https://kapi.kakao.com/v1/user/logout" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: KakaoAK ${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

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

URL
GET /oauth/logout?client_id=${REST_API_KEY}&logout_redirect_uri=${LOGOUT_REDIRECT_URI} HTTP/1.1
Host: kauth.kakao.com
Parameter
Name Type Description Required
client_id String REST API key that Kakao issues when you create 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

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

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.

CAUTION

Keep your app's Admin key safe not to be revealed. You should make REST API requests with an Admin key only in the server, NOT in your source code.

Request: Using access token

URL
POST /v1/user/unlink HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer ${ACCESS_TOKEN}
O

Request: Using admin key

URL
POST /v1/user/unlink HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK ${APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
target_id_type String A type of a service user ID.
Fixed as user_id.
O
target_id Long Service user ID to be unlinked from the service. O

Response

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" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
Request: Using admin key
curl -v -X POST "https://kapi.kakao.com/v1/user/unlink" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -H "Authorization: KakaoAK ${APP_ADMIN_KEY}" \
  -d "target_id_type=user_id" \
  -d "target_id=123456789" 
Response
{
  "id": 123456789
}

Retrieve token information

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

URL
GET /v1/user/access_token_info HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer ${ACCESS_TOKEN}
O

Response

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

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

URL
POST /oauth/token HTTP/1.1
Host: kauth.kakao.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
Parameter
Name Type Description Required
grant_type String Fixed as refresh_token. O
client_id String REST API key that Kakao issues when you create 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] > [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

Name Type Description Required
token_type String A type of a token, fixed as 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" \
 -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":"wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww",
    "token_type":"bearer",
    "refresh_token":"zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",  //optional
    "refresh_token_expires_in":25184000,  //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":"wwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwwww",
    "expires_in":43199,
    "id_token":"eyJraWQiOiJlYTVkMjU1ZjM0OTIxZDRhNmNhMTBmNmNhZGYyNzAiLCJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIyMDU3OTciLCJzdWIiOiI0MjkyNCIsImF1dGhfdGltZSI6MTY0NDgzMzMzNiwiaXNzIjoiaHR0cHM6Ly9rYXV0aC5rYWthby5jb20iLCJleHAiOjE2NDQ4NDA1NTIsImlhdCI6MTY0NDgzMzM1Mn0.GtvPDeOHw1JYE6sBsUw0MSexiE31cNIwl43VNERcGPK8JvKAAyq8MmUqmNvzwtTlGhXf8KuBVBv5Hfc21f3i70O-I35HlG_5gMBZe4gjeDdTSxzpQEaMLPCRJpfoqI2FdpE9SsIHVphji4MM1BX6NSmpdF6EqAT_Eu_NLVqp-aM2jEt8bC6sVvyR5Ly4OHLFMdnpiatuZwgzkGMTdafD3YLl0uyKbyRkIZQZKyTeXxRhqqSVfBXR5B8ZoC1pB4BqoFTrLl3TI4qdTWwu_NF-ulxKCiyPuTRo1ZuOeyNr9r3-X_gOzeT_slXvXVeOzJWHszd9C2CsNR53w5izgzSfrw",
    "refresh_token":"zzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzzz",  //optional
    "refresh_token_expires_in":25184000  //optional
}

Retrieve user information Consent required

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.

IMPORTANT

To retrieve user data, you must set consent items and obtain user's consent for the data that your service needs. If a user does not consent, you cannot get the user data. To 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

Request: Using access token

URL
GET/POST /v2/user/me HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer ${ACCESS_TOKEN}
O
Parameter
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"])
X

Request: Using admin key

URL
GET/POST /v2/user/me HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK ${APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
target_id_type String A type of a service user ID.
Fixed as 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"])
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.

Response

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

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

IMPORTANT: Providing separated scopes for profile information

From June 25, 2021, we provide the profile information separated as 'Nickname' and 'Profile image'. You can request consent to desired profile information by setting desired scopes respectively. If you create a new app, the separated scopes for profile information are applied to the app. If you have enabled the 'Profile Info(nickname/profile image)' scope, you can continue to use that scope. In this case, you do not need to change the app settings, and there is no change in API response. But if you want to use the new scpes in the existing app, fill out the request form. In this case, the API response may change. Refer to Notice for more details.

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

Sample

Request: All information using access token
curl -v -X 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" \
  -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" \
  -H "Authorization: KakaoAK ${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
        },
        "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}",
        ...
    }
}
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 Consent required

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

To retrieve shipping address,

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

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

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.

Request: Using access token

URL
GET v1/user/shipping_address HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer ${ACCESS_TOKEN}
O
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 admin key

URL
GET v1/user/shipping_address HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK ${APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
target_id_type String A type of a service user ID.
Fixed as user_id.
O
target_id Long Service user ID. O

Response

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.

shipping_addresses
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 since some old type of addresses may not have a zip code.
X

Sample

Request: Using access token
curl -v -X GET "https://kapi.kakao.com/v1/user/shipping_address" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}"
Request: Using admin key
curl -v -G GET "https://kapi.kakao.com/v1/user/shipping_address" \
  -H "Authorization: KakaoAK ${APP_ADMIN_KEY}" \
  -d "target_id_type=user_id" \
  -d "target_id=${USER_ID}"
Response
{
  "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

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

Policy change on the user properties related to user profile

'properties.profile_image', 'properties.thumbnail_image', and 'properties.nickname' have been deprecated on May 12, 2022 as Kakao Account's profile information is reflected in real time to the property keys. Thus, you cannot pass these property keys in your request. For more details, refer to Notice.

Request

URL
POST /v1/user/update_profile HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer ${ACCESS_TOKEN}
O
Parameter
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

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

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.

CAUTION

You must keep your Admin key safe not to be revealed. Thus, when you use the Admin key, call the Retrieving user information API only from a server.

Request

URL
GET /v1/user/ids HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK ${APP_ADMIN_KEY}
O
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 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

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

'total_count', the response field of the Retrieving user list API, will be deprecated on January 10, 2022. 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 -X GET "https://kapi.kakao.com/v1/user/ids" \
  -H "Authorization: KakaoAK ${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 ${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

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","kakao_account.has_email"]

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.has_email, 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

URL
GET /v2/app/users HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK ${APP_ADMIN_KEY}
O
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 as 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.
If not specified, default information is returned only in response.
X

Response

Name Type Description Required
elements List<users_info> 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
users_info
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 JSON 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 ${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 ${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
[
    {
        "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
[
    {
        "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
            },
            "has_email":true,
            "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
            },
            "has_email":true,
            "email_needs_agreement":true
            }
    }
    ...
]
Response: All available user information

Request additional consent

IMPORTANT: Set consent items

To use this API, you must configure consent items for the required scopes.

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.

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

URL
GET /oauth/authorize?client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code&scope={required_scopes.join(',')} HTTP/1.1
Host: kauth.kakao.com
Parameter
Name Type Description Required
client_id String REST API key that Kakao issues when you create 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 as 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

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

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

URL
GET /v2/user/scopes HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer ${ACCESS_TOKEN}
O
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 admin key

URL
GET /v2/user/scopes HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK ${APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
target_id_type String A type of a service user ID.
Fixed as 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

Name Type Description Required
id Long Service user ID. O
scopes scopes[] List of scope information. O
scopes
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 -X 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 admin key
curl -v -G GET "https://kapi.kakao.com/v2/user/scopes" \
    -H "Authorization: KakaoAK ${APP_ADMIN_KEY}" \
    -d "target_id_type=user_id" \
    -d "target_id=123456789" 
Response: Success
{
    "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
{
    "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

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

URL
POST /v2/user/revoke/scopes HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer ${ACCESS_TOKEN}
O
Parameter
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 admin key

URL
POST /v2/user/revoke/scopes HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK ${APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
target_id_type String A type of a service user ID.
Fixed as 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

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" \
    -H "Authorization: Bearer ${ACCESS_TOKEN}" \
    --data-urlencode 'scopes=["account_email"]'
Request: Using admin key
curl -v -X POST "https://kapi.kakao.com/v2/user/revoke/scopes" \
    -H "Content-Type: application/x-www-form-urlencoded" \
    -H "Authorization: KakaoAK ${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
{
    "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
}

Check user agreed terms

IMPORTANT

This API is only allowed for the service that adopted Kakao Sync. To see the advantages of Kakao Sync, refer to Concept > Kakao Sync. Before implementing this API, read Design terms and policies.

This API enables you to check the Terms of Service that a user has consented to.

You can send a GET request using either an access token or your app's Admin key to use this API. For a service administrator to check the terms that a specific user has consented to, the app's Admin key can be used.

If you use the Admin key when you request,

  • You must call this API only from the server to avoid security risk. Otherwise, your Admin key might be revealed.
  • You must pass both target_id_type and target_id in your request.
  • Specify a user's service user ID through target_id, and set target_id_type to user_id.

The response includes the requested user's service user ID, each term's tag, and the last time a user consented to the term. When a user attempts to log in after deleting the service account or unlinking from the app, the user goes through the Simple-signup process again. According to the time the user consents, the time information is updated.

Request: Using access token

URL
GET /v1/user/service/terms HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer ${ACCESS_TOKEN}
O
Parameter
Name Type Description Required
extra String Used to retrieve all of the terms registered in your app.
In this case, set it to extra=app_service_terms.
X

Request: Using admin key

URL
GET /v1/user/service/terms HTTP/1.1
Host: kapi.kakao.com
Authorization: KakaoAK ${APP_ADMIN_KEY}
Header
Name Description Required
Authorization Admin key as a type of user authentication.
Authorization: KakaoAK ${APP_ADMIN_KEY}
O
Parameter
Name Type Description Required
target_id_type String A type of a service user ID.
Fixed as user_id
O
target_id Long Service user ID. O
extra String Used to retrieve all of the terms registered in your app.
In this case, set it to extra=app_service_terms.
X

Response

Name Type Description Required
user_id Long Service user ID. O
app_service_terms AppServiceTerms[] A list of terms registered for an app. X
allowed_service_terms AllowedServiceTerms[] A list of terms that a user has consented to. X
AppServiceTerms
Name Type Description Required
tag String Tag that is specified in [My Application] > [Simple Signup] for each term. O
created_at Datetime The time when the term was registered.
(RFC3339 internet date/time format)
O
updated_at Datetime The time when the term was modified.
(RFC3339 internet date/time format)
O
AllowedServiceTerms
Name Type Description Required
tag String Tag of the term that a user consented to. O
agreed_at Datetime The last time when a user consented to the term.
(RFC3339 internet date/time format)
O

Sample

Request: Using access token
curl -v -X GET "https://kapi.kakao.com/v1/user/service/terms" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
Request: Using admin key
curl -v -X GET "https://kapi.kakao.com/v1/user/service/terms?target_id_type=user_id&target_id=111111" \
-H "Authorization: KakaoAK ${APP_ADMIN_KEY}"
Request: A list of terms set for an app, using access token
curl -v -X GET "https://kapi.kakao.com/v1/user/service/terms?extra=app_service_terms" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
Response: Success, the agreed terms return
{
 "user_id": 111111,
 "allowed_service_terms": [
  {
   "tag": "service_20190101",
   "agreed_at": "2019-05-10T10:33:26Z"
  },
  {
   "tag": "privacy_20190102",
   "agreed_at": "2019-05-10T10:33:26Z"
  }
 ]
}
Response: The agreed terms and a list of terms set for an app return
{
 "user_id": 111111,
 "allowed_service_terms": [
    {
    "tag": "age",
    "agreed_at": "2020-06-18T05:58:35Z"
    },
    {
    "tag": "additional_requirement_202002",
    "agreed_at": "2020-06-18T05:58:35Z"
    },
    {
    "tag": "service_20190326",
    "agreed_at": "2020-06-18T05:58:35Z"
    },
    {
    "tag": "privacy_20190326",
    "agreed_at": "2020-06-18T05:58:35Z"
    }
 ],
 "app_service_terms": [
    {
    "tag": "additional_requirement_202002",
    "created_at": "2020-02-14T06:10:36Z",
    "updated_at": "2020-02-14T07:59:07Z"
    },
    {
    "tag": "age",
    "created_at": "2020-03-24T01:12:46Z",
    "updated_at": "2020-03-24T01:12:46Z"
    },
    {
    "tag": "option1",
    "created_at": "2019-10-29T01:37:11Z",
    "updated_at": "2019-10-29T01:37:11Z"
    },
    {
    "tag": "privacy_20190326",
    "created_at": "2019-03-26T11:36:29Z",
    "updated_at": "2019-03-26T11:36:29Z"
    },
    {
    "tag": "required_111",
    "created_at": "2020-06-18T05:59:38Z",
    "updated_at": "2020-06-18T05:59:38Z"
    },
    {
    "tag": "service2_20190527",
    "created_at": "2019-05-27T02:49:06Z",
    "updated_at": "2019-10-16T05:24:58Z"
    },
    {
    "tag": "service_20190326",
    "created_at": "2019-03-26T11:36:29Z",
    "updated_at": "2019-03-26T11:36:29Z"
    }
 ]
}

Get consent to desired terms

IMPORTANT

This API is only allowed for the service that adopted Kakao Sync. To see the advantages of Kakao Sync, refer to Concept > Kakao Sync. Before implementing this API, read Design terms and policies.

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

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

CAUTION: Specify tags when using additional parameter

When you use 'service_terms' when you request this API, you must specify the tags for the terms that the consent is required. If not, all terms are not displayed on the Consent screen. In this case, a user who has signed up through Simple Signup can log in without consenting to all terms of services. To prevent a problem, you should test this feature before applying it to your actual service.

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 term's tag in 'Term's TAG' on the Simple Signup page where you registered the terms. For multiple tags, separate the terms by comma(,).

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

Request

URL
GET /oauth/authorize?client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code&service_terms={REGISTERED_TERMS) HTTP/1.1
Host: kauth.kakao.com
Parameter
Name Type Description Required
client_id String REST API key that Kakao issues when you create 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 as code. O
service_terms Sting Tags for the 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 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}

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:

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

- After you get an ID token, you must verify ID token. To get a public key required to verify an ID token, see Get public key. - If you use the scope parameter, you must add 'openid' to 'scope' for OIDC. If not, you cannot get an ID token as the OAuth protocol, instead of OIDC, is applied.

What you can do

After you get an ID token, you can:

Get public key

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.

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

Request

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

Response

Name Type Description Required
keys Keys Array of JSON Web Keys.
Refer to JSON Web Key (RFC 7517).
O
Keys
Name Type Description Required
kid String Public key ID. O
kty String Type of public key. Fixed as RSA. O
alg String Algorithm intended for use with the key. Fixed as RS256. O
use String Intended use of the public key. Fixed as sig (signature). O
n String Modulus value for public key. O
e String Exponent value for public key. O

Sample

Request
curl -v -X 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

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.

You can retrieve the metadata required while implementing OIDC by accessing the following URI:

https://kauth.kakao.com/.well-known/openid-configuration

Response

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
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
response_types_supported String[] Value of response_type used for OAuth 2.0 authorization.
Only code is returned.
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 -X GET "https://kauth.kakao.com/.well-known/openid-configuration"
Response
HTTP/1.1 200 OK
{
    "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",
    "subject_types_supported":[
        "public"
    ],
    "id_token_signing_alg_values_supported":[
        "RS256"
    ],
    "response_types_supported":[
        "code"
    ],
    "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

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.

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

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

URL
GET /v1/oidc/userinfo HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer ${ACCESS_TOKEN}
O

Response

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

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 imageused 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 since 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 -X 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

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

CAUTION

This API is intended for debugging only. You cannot use this API to validate the ID token in your actual service. The requests for unintended use may be blocked.

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

URL
POST /oauth/tokeninfo HTTP/1.1
Host: kauth.kakao.com
Content-type: application/x-www-form-urlencoded;charset=utf-8
Header
Name Description Required
id_token ID token that you want to decode. X

Response

Name Type Description Required
iss String Issuer Identifier.
Fixed as 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

IMPORTANT

The Manual signup API is only for the app that the Auto-link option is disabled. To check whether to use this feature, go to [My Application] > [Kakao Login] and see if the 'Auto-link with an app when logging in' option is displayed. If not displayed, your app is using the Auto-link feature. If displayed, you can choose whether to automatically link a user with your app when the user logs in. If this option is set to 'Disabled', you must use the Manual signup API to link the user.

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.

Unlink for users who have not completed a signup

If a user is not linked using the Manual signup API in the preregister state within 24 hours, the user is considered as not signed up and turned to be in an unlink state. If you register unlink callback, you will get an unlink callback when a user unlinks from your app. In this case, you must call the unlink API for the user and delete the user information. For more details, refer to Notice.

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

URL
POST /v1/user/signup HTTP/1.1
Host: kapi.kakao.com
Authorization: Bearer ${ACCESS_TOKEN}
Content-type: application/x-www-form-urlencoded;charset=utf-8
Header
Name Description Required
Authorization Access token as a type of user authentication.
Authorization: Bearer ${ACCESS_TOKEN}
O
Parameter
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

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