REST API

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

REST API Test Tooloutlink

Get business authorization code

Basic information

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:

  • Authorization code issued successfully. Use the business authorization code value from code to request the Get business token.

• When error and error_description are provided:

  • Authorization code issuance failed. Refer to Troubleshooting and handle the situation by displaying an appropriate service page or message to the user based on the cause of the error.

Request

Query parameters

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 Ad ResourceId: 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

Response

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.

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

Sample

Request

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}

Request: All Kakao Moment ad accounts of the user

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

Request: Specific Kakao Moment ad account of the user

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}

Request: Specific Kakao Moment and Keyword Ad accounts of the user

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}

Request: User selects directly

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

Response: User selects [Agree and Continue], Business authorization code issued

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

Get business token

Basic information

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.

Request

Header

Name	Description	Required
Content-Type	Content-Type: application/x-www-form-urlencoded;charset=utf-8 Request data type	O

Body

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

Response

Body

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

Sample

Request

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

Response

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

Retrieve business token information

Basic information

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.

Request

Header

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

Response

Body

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

BizAgreement

Name	Type	Description	Required
group	String	Type of Business consent items, one of the following: PERSONAL: Personal information MOMENT: Kakao Moment KEYWORD: 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

Sample

Request

curl -X GET "https://kapi.kakao.com/v1/business/tokeninfo" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}"

Response

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

Retrieve business user information

Basic information

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.

Request

Header

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

Response

Body

Name	Type	Description	Required
token_user_id	String	User's business authentication membership number	O
email	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

Sample

Request

curl -X GET "https://kapi.kakao.com/v1/business/userinfo" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}"

Response: Including user's email information

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "token_user_id": "${TOKEN_USER_ID}",
    "email": "${EMAIL}",
    "email_verified": true
}

Revoke business token

Basic information

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.

Request

Header

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

Response

Body

Name	Type	Description	Required
id	String	Business token ID.	O
token_user_id	String	User's Business Authentication ID.	O

Sample

Request

curl -X POST "https://kapi.kakao.com/v1/business/revoke" \
    -H "Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}"

Response

HTTP/1.1 200 OK
Content-Type: application/json;charset=UTF-8
{
    "id": "${ID}",
    "token_user_id": "${TOKEN_USER_ID}"
}