This document describes how to integrate Business Authentication APIs into your service with a REST API.
You can test some features described in this document in [Tools] > [REST API Test].
Method | URL | Authentication |
---|---|---|
GET |
https://kauth.kakao.com/oauth/business/authorize |
- |
Permissions | Prerequisites | Business Authentication | Business consent items |
---|---|---|---|
Required: Request permission | Switch to a Biz app Set Business redirect URI Business consent items |
Required | Required |
Request to issue a business authorization code by invoking the Business consent screen. The business consent screen requests the user's authorization (consent) for the Business consent items specified in the request.
Make a GET
request including the service app's REST API key and the business consent item ID. The business consent item IDs can be found in the Business consent items or under [My Application] > [Business Authentication] > [Consent Items].
If the request succeeds, the user sees the business consent screen. The user can choose whether to accept the consent items on that screen. The Kakao API platform redirects (HTTP 302) the result as a query string to the redirect_uri
. The redirect URI must be one of the values registered in [My Application] > [Business Authentication] > [Redirect URI].
The service server must check the authorization code or error from the Location
of the HTTP 302 redirected request to the redirect_uri
and handle it as follows.
When code
and state
are provided:
code
to request the Get business token.When error
and error_description
are provided:
The Business consent screen will always be displayed with each request, regardless of the user's previous consent. Ensure not to issue business tokens redundantly with the same authorization code that holds the same consent details.
Name | Type | Description | Required |
---|---|---|---|
client_id | String |
Service app REST API key. Can be found in [My Application] > [App Key]. |
O |
response_type | String |
Fixed as code . |
O |
redirect_uri | String |
URI of the service server that will receive the business authorization code. Registered in [My Application] > [Business authentication] > [Redirect URI]. |
O |
scope | String |
List of business consent item IDs to request Authorization from the user. Consent item IDs can be found in Business consent items or in [My Application] > [Business authentication] > [Consent Items]. Multiple values can be passed, separated by commas (,). Note: biz_account_email cannot be passed alone; it must be passed along with other business consent item IDs.Note: When requesting authorization for Create advertising accounts ( _create ), it is necessary to specify the entire ad account belonging to the ScopeGroup by passing resource_ids as ScopeGroup:* . |
O |
state | String |
An arbitrary string that maintains the same value during the business authentication process (no fixed format). Used to protect business authentication requests from Cross-Site Request Forgery (CSRF) attacks. The state value must be unique for each user's authentication request.The validity of the request and response can be verified by checking whether the state values match in the authorization code request, authorization code response, and token issuance request. |
X |
resource_ids | String[] |
Specifies the user's Business assets to request authorization for (default: none, user selects on the consent screen). Multiple values can be passed in the format ScopeGroup:ResourceId , see below and Sample.ScopeGroup : Kakao Business service code, one of the following:- moment : Kakao Moment- keyword : Keyword AdResourceId : Business assets ID.If * is passed, the request targets all assets belonging to the ScopeGroup held by the user.Note: When requesting authorization for Create advertising accounts ( _create ), it is necessary to specify the entire ad account belonging to the ScopeGroup by passing resource_ids in the format ScopeGroup:* . |
X |
The response of the Get business authorization code is redirected (HTTP 302
) and sent to the redirect_uri
via a GET
request. This request includes the following query parameters.
Name | Type | Description | Required |
---|---|---|---|
code | String |
Business authorization code required for the Get business token request | X |
error | String |
Error code returned when authentication fails. | X |
error_description | String |
Error message returned when authentication fails. | X |
state | String |
Same value as the state parameter provided in the request |
X |
https://kauth.kakao.com/oauth/business/authorize?client_id=${REST_API_KEY}&response_type=code&redirect_uri=${REDIRECT_URI}&scope=${SCOPE_ID}&resource_ids=${RESOURCE_IDS}
https://kauth.kakao.com/oauth/business/authorize?client_id=${REST_API_KEY}&response_type=code&redirect_uri=${REDIRECT_URI}&scope=moment_create,moment_management,moment_delete&resource_ids=moment:*
https://kauth.kakao.com/oauth/business/authorize?client_id=${REST_API_KEY}&response_type=code&redirect_uri=${REDIRECT_URI}&scope=moment_create,moment_management,moment_delete&resource_ids=moment:${AD_ACCOUNT_ID}
https://kauth.kakao.com/oauth/business/authorize?client_id=${REST_API_KEY}&response_type=code&redirect_uri=${REDIRECT_URI}&scope=moment_create,moment_management,moment_delete,keyword_management&resource_ids=moment:${AD_ACCOUNT_ID}&resource_ids=keyword:${AD_ACCOUNT_ID}
https://kauth.kakao.com/oauth/business/authorize?client_id=${REST_API_KEY}&response_type=code&redirect_uri=${REDIRECT_URI}&scope=moment_create,moment_management,moment_delete
HTTP/1.1 302 Found
Content-Length: 0
Location: ${REDIRECT_URI}?code=${AUTHORIZE_CODE}
Method | URL | Authentication |
---|---|---|
POST |
https://kauth.kakao.com/oauth/business/token |
- |
Permissions | Prerequisites | Business Authentication | Business consent items |
---|---|---|---|
Required: Request permission | Switch to a Biz app Set Business redirect URI Business consent items |
Required | Required |
Request to issue a business token by using a business authorization code.
Make a POST
request including the required parameters. If the request succeeds, the response contains the business token and token information. For details on the business token, see Business token. If the request fails, see Troubleshooting for details.
Name | Description | Required |
---|---|---|
Content-type | Content-type: application/x-www-form-urlencoded;charset=utf-8 Request data type |
O |
Name | Type | Description | Required |
---|---|---|---|
grant_type | String |
Fixed as authorization_code . |
O |
client_id | String |
Service app REST API key. Can be found under [My Application] > [App Key]. |
O |
code | String |
Business authorization code obtained from the Get business authorization code. | O |
redirect_uri | String |
URI where the business authorization code is redirected. The value registered in [My Application] > [Business Certification] > [Redirect URI]. |
O |
Name | Type | Description | Required |
---|---|---|---|
token_type | String |
Token type, fixed as bearer . |
O |
access_token | String |
Value of the Business token. | O |
scope | String |
Business consent items assigned to the business token. Separated by spaces if multiple. |
O |
curl -v -X POST "https://kauth.kakao.com/oauth/business/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=${AUTHORIZE_CODE}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"access_token":"${BUSINESS_ACCESS_TOKEN}",
"token_type":"bearer",
"scope":"moment_create moment_management moment_delete"
}
Method | URL | Authentication |
---|---|---|
GET |
https://kapi.kakao.com/v1/business/tokeninfo |
Business token |
Permissions | Prerequisites | Business Authentication | Business consent items |
---|---|---|---|
Required: Request permission | Switch to a Biz app Set Business redirect URI Business consent items |
- | - |
Request to verify the validity of the business token or retrieve its information.
Make a GET
request including the business token in the header. If the request succeeds, the response contains the user's business authentication member number, the consented Business consent items, and the status of the business token. If the request fails, see Troubleshooting for details.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} Business token as a type of user authentication. |
O |
Name | Type | Description | Required |
---|---|---|---|
id | String |
Business token ID | O |
token_user_id | String |
User's Business Authentication user ID. | O |
biz_agreements | BizAgreement[] |
List of Business consent items the user has agreed to. | O |
status | String |
Business token status, fixed as active . |
O |
updated_at | Datetime |
Most recent change date of the business token, UTC. | O |
Name | Type | Description | Required |
---|---|---|---|
group | String |
Type of Business consent items, one of the following:PERSONAL : Personal informationMOMENT : Kakao MomentKEYWORD : Keyword Ad |
O |
scope | String[] |
List of Business consent items IDs the user has agreed to | O |
ad_account_ids | String[] |
List of ad account IDs with access permission. If the value is * , the user has access to all ad accounts owned within the group . |
X |
channel_public_ids | String[] |
List of KakaoTalk channel profile IDs with access permission. | X |
curl -X GET "https://kapi.kakao.com/v1/business/tokeninfo" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": "${ID}",
"token_user_id": "${TOKEN_USER_ID}",
"biz_agreements": [
{
"group": "personal",
"scope": [
"biz_account_email"
]
},
{
"group": "keyword",
"scope": [
"keyword_management",
"keyword_create",
"keyword_delete"
],
"ad_account_ids": [
"*"
]
}
],
"status": "ACTIVE",
"updated_at": "2024-08-21T01:56:59Z"
}
Method | URL | Authentication |
---|---|---|
GET |
https://kapi.kakao.com/v1/business/userinfo |
Business token |
Permissions | Prerequisites | Business Authentication | Business consent items |
---|---|---|---|
Required: Request permission | Switch to a Biz app Set Business redirect URI Business consent items |
- | - |
Request to retrieve business user information.
Make a GET
request including The user's business token in the header. If the request succeeds, the response contains user's Business Authentication ID and email. If the request fails, see Troubleshooting for details.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} Business token as a type of user authentication. |
O |
Name | Type | Description | Required |
---|---|---|---|
token_user_id | String |
User's business authentication membership number | O |
String |
Kakao Account primary email Required business consent item: Email |
X | |
email_verified | Boolean |
Whether the Kakao Account primary email is verified and valid.true : Verified valid email.false : Unverified or invalid email used by another Kakao Account. |
X |
curl -X GET "https://kapi.kakao.com/v1/business/userinfo" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"token_user_id": "${TOKEN_USER_ID}",
"email": "${EMAIL}",
"email_verified": true
}
Method | URL | Authentication |
---|---|---|
POST |
https://kapi.kakao.com/v1/business/revoke |
Business token |
Permissions | Prerequisites | Business Authentication | Business consent items |
---|---|---|---|
Required: Request permission | Switch to a Biz app Set Business redirect URI Business consent items |
- | - |
Request to revoke an issued business token.
Make a POST
request including the business token in the header. If the request succeeds, the response contains the revoked business token ID and the user's Business Authentication ID. If the request fails, see Troubleshooting for details.
Name | Description | Required |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} Business token as a type of user authentication. |
O |
Name | Type | Description | Required |
---|---|---|---|
id | String |
Business token ID. | O |
token_user_id | String |
User's Business Authentication ID. | O |
curl -X POST "https://kapi.kakao.com/v1/business/revoke" \
-H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}"
HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
"id": "${ID}",
"token_user_id": "${TOKEN_USER_ID}"
}