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.
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.
redirect_uri
.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.
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.
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.
The response is redirected to the redirect_uri
as a GET
request with the query parameters below.
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 |
https://kauth.kakao.com/oauth/authorize?response_type=code&client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}
https://kauth.kakao.com/oauth/authorize?response_type=code&client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&nonce=${NONCE}
HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?code=${AUTHORIZATION_CODE}
HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?error=access_denied&error_description=User%20denied%20access
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.
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.
Name | Description | Required |
---|---|---|
Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8 The data type of the request. |
O |
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 |
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 |
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}"
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"
}
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}"
}
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.
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 |
The response is redirected to the redirect_uri
as a GET
request with the query parameters below.
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 |
https://kauth.kakao.com/oauth/authorize?response_type=code&client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&prompt=none
HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?code=${AUTHORIZATION_CODE}
HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?error=consent_required&error_description=user%20consent%20required.
HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?error=login_required&error_description=user%20authentication%20required.
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 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.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication. |
O |
Name | Description | Required |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication. |
O |
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 |
Name | Type | Description | Required |
---|---|---|---|
id | Long |
Service user ID that has been logged out. | O |
curl -v -X POST "https://kapi.kakao.com/v1/user/logout" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
curl -v -X POST "https://kapi.kakao.com/v1/user/logout" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-d "target_id_type=user_id" \
-d "target_id=123456789"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id":123456789
}
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.
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 |
The response is redirected to the logout_redirect_uri
as a GET
request with the query parameters below.
Name | Type | Description | Required |
---|---|---|---|
state | String |
If state is included in the request, the same value as the request must be returned. |
X |
curl -v -G GET "https://kauth.kakao.com/oauth/logout?client_id=${YOUR_REST_API_KEY}&logout_redirect_uri=${YOUR_LOGOUT_REDIRECT_URI}"
HTTP/1.1 302 Found
Location: ${LOGOUT_REDIRECT_URI}?state=${STATE}
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.
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.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication. |
O |
Name | Description | Required |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication. |
O |
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 |
Name | Type | Description | Required |
---|---|---|---|
id | Long |
Service user ID that has been successfully unlinked from the service. | O |
curl -v -X POST "https://kapi.kakao.com/v1/user/unlink" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
curl -v -X POST "https://kapi.kakao.com/v1/user/unlink" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-d "target_id_type=user_id" \
-d "target_id=123456789"
{
"id": 123456789
}
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.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication. |
O |
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 |
curl -v -G GET "https://kapi.kakao.com/v1/user/access_token_info" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
HTTP/1.1 200 OK
{
"id":123456789,
"expires_in": 7199,
"app_id":1234
}
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.
Name | Description | Required |
---|---|---|
Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8 The data type of the request. |
O |
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 |
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 |
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}"
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,
}
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}",
}
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.
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 |
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 |
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.
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 |
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 |
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 : Preregisteredtrue : 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.
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 |
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.
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.
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 nicknamefalse : Not the default nicknameRequired user consent: Profile Info(nickname/profile image) or Nickname |
X |
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 |
curl -v -G GET "https://kapi.kakao.com/v2/user/me" \
-H "Authorization: Bearer ${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"]'
curl -v -X POST "https://kapi.kakao.com/v2/user/me" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-d "target_id_type=user_id" \
-d "target_id=123456789" \
--data-urlencode 'property_keys=["kakao_account.email"]'
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}"
}
}
HTTP/1.1 200 OK
{
"id":123456789,
"kakao_account": {
"profile__nickname_needs_agreement": false,
"profile": {
"nickname": "Ryan"
},
},
"properties":{
"${CUSTOM_PROPERTY_KEY}": "${CUSTOM_PROPERTY_VALUE}",
...
}
}
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.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication. |
O |
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 |
Name | Description | Required |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication. |
O |
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 |
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.
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 |
curl -v -G GET "https://kapi.kakao.com/v1/user/shipping_address" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
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}"
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
}
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.
'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.
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 |
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 |
Name | Type | Description | Required |
---|---|---|---|
id | Long |
Service user ID. | O |
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}"}'
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id":123456789
}
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.
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.
Name | Description | Required |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication. |
O |
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 |
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.
curl -v -G GET "https://kapi.kakao.com/v1/user/ids" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}"
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'
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"
}
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.
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 |
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 |
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 |
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.
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]"
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"]'
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"]'
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"
}
...
]
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
}
}
...
]
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.
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 |
https://kauth.kakao.com/oauth/authorize?client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code&scope=account_email,gender
https://kauth.kakao.com/oauth/authorize?client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code&scope=openid,account_email,gender
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.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication. |
O |
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 |
Name | Description | Required |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication. |
O |
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 |
Name | Type | Description | Required |
---|---|---|---|
id | Long |
Service user ID. | O |
scopes | Scope[] |
List of scope information. | O |
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 |
curl -v -G GET "https://kapi.kakao.com/v2/user/scopes" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
curl -v -G GET "https://kapi.kakao.com/v2/user/scopes" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
--data-urlencode 'scopes=["account_email","friends"]'
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"
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
},
...
]
}
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
}
]
}
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
.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication. |
O |
Name | Type | Description | Required |
---|---|---|---|
scopes | String[] |
List of scope IDs you want to revoke. You can revoke only the scope with "revocable":true among the scopes retrieved through the Retrieving consent details API. |
O |
Name | Description | Required |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication. |
O |
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 |
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"]'
curl -v -X POST "https://kapi.kakao.com/v2/user/revoke/scopes" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY}" \
-d "target_id_type=user_id" \
-d "target_id=123456789" \
--data-urlencode 'scopes=["account_email"]'
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
},
...
]
}
HTTP/1.1 403 Forbidden
{
"msg":"[profile] is not revocable. check out if it's set as required on developers.kakao.com",
"code":-3
}
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
}
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 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 service terms and policies.
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.
When you use 'service_terms' when you request this API, you must specify the tags for the service terms that the consent is required. If not, all service 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 service terms. 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 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.
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 |
https://kauth.kakao.com/oauth/authorize?client_id=${REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code&service_terms=tag1,tag2
HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?code=${AUTHORIZATION_CODE}
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 is only allowed for the service that adopted Kakao Sync.
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.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication. |
O |
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 |
Name | Description | Required |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication. |
O |
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 |
Name | Type | Description | Required |
---|---|---|---|
id | Long |
Service user ID. | O |
service_terms | ServiceTerms[] |
List of service terms. | X |
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 : Agreedfalse : Disagreed |
O |
revocable | Boolean |
Whether consent is revocable in the service terms.true : Can be revokedfalse : Cannot be revoked, is in a disagreed state or is a required Term of ServiceNote: 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 |
curl -v -G GET "https://kapi.kakao.com/v2/user/service_terms" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
curl -v -G GET "https://kapi.kakao.com/v2/user/service_terms" \
-H 'Authorization: Bearer ${ACCESS_TOKEN}' \
-d "result=app_service_terms"
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"
{
"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"
},
...
]
}
{
"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"
},
...
]
}
{
"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"
}
]
}
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
}
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 | - |
This API is only allowed for the service that adopted Kakao Sync.
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.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication. |
O |
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 |
Name | Description | Required |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication. |
O |
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 |
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 |
Name | Type | Description | Required |
---|---|---|---|
tag | String |
Tag of revoked service terms | O |
agreed | Boolean |
The consent status of the service terms after revocation.true : Agreedfalse : Disagreed |
O |
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"
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"
{
"id": 111111,
"revoked_service_terms": [
{
"tag": "optional_20200616",
"agreed": false
},
{
"tag": "optional_no_consent",
"agreed": false
}
]
}
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
}
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 is only allowed for the service that adopted Kakao Sync.
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.
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.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication. |
O |
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 |
Name | Description | Required |
---|---|---|
Authorization | Authorization: KakaoAK ${SERVICE_APP_ADMIN_KEY} Service app admin key as a type of user authentication. |
O |
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 |
Name | Type | Description | Required |
---|---|---|---|
id | Long |
Service user ID. | O |
agreed_service_terms | AgreedServiceTerms[] |
List of service terms that successfully set consent. | X |
Name | Type | Description | Required |
---|---|---|---|
tag | String |
Tag of agreed service terms | O |
agreed | Boolean |
The consent status of the service terms after revocation.true : Agreedfalse : 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 |
curl -v -X POST "https://kapi.kakao.com/v2/internal/user/upgrade/service_terms" \
-H "Authorization: Bearer ${ACCESS_TOKEN}" \
-d "tags=term01,term02,term03"
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"
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"
}
]
}
HTTP/1.1 200 OK
{
"id": 1376016924429759243,
"agreed_service_terms": [
{
"tag": "term02",
"agreed": true,
"agreed_at": "2023-08-02T08:34:56Z"
}
]
}
OpenID Connect (OIDC) is an extended version added to the top of the OAuth protocol, used to authenticate users.
If you want to integrate Kakao Login with OIDC, you need to get an ID Token as follows:
- 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. - To use user information included in the ID token, you must call one of the APIs that retrieve user information the first time when a user logs in with Kakao. See Retrieving user information for OIDC.
After you get an ID token, you can:
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.
Name | Type | Description | Required |
---|---|---|---|
keys | JWK[] |
Array of JSON Web Keys. Refer to JSON Web Key (RFC 7517). |
O |
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 |
curl -v -G GET "https://kauth.kakao.com/.well-known/jwks.json"
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"
}
]
}
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.
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 |
curl -v -G GET "https://kauth.kakao.com/.well-known/openid-configuration"
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"
]
}
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.
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.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${ACCESS_TOKEN} Access token as a type of user authentication. |
O |
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 |
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 |
curl -v -G GET "https://kapi.kakao.com/v1/oidc/userinfo" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
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
}
HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token"
{
"msg":"this access token does not exist",
"code":-401
}
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.
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.
Name | Description | Required |
---|---|---|
Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8 The data type of the request. |
O |
Name | Description | Required |
---|---|---|
id_token | ID token that you want to decode. | X |
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 |
String |
Email saved in Kakao Account. Only returned is_email_valid is true .Required user consent: Email NOTE: Cautions when using email |
X |
curl -v -X POST "https://kauth.kakao.com/oauth/tokeninfo" \
-d "id_token=${ISSUED_ID_TOKEN}"
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"
}
HTTP/1.1 400 Bad Request
{
"error": "invalid_token",
"error_description": "invalid id_token format",
"error_code": "KOE400"
}
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 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:
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.
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.
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 |
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 |
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 |
Name | Type | Description | Required |
---|---|---|---|
id | Long |
Service user ID that is linked to your app. | O |
curl -v -X POST "https://kapi.kakao.com/v1/user/signup" \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"
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}"}'
HTTP/1.1 200 OK
{
"id":1376016924429759228
}
HTTP/1.1 400 Bad Request
{
"msg":"already registered",
"code":-102
}
HTTP/1.1 401 Unauthorized
{
"msg":"this access token does not exist",
"code":-401
}
HTTP/1.1 400 Bad Request
{
"msg":"user property not found ([gender, age] for appId={APP_ID})",
"code":-201
}