Business Authentication

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

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	REST API key Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Issues 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 [Business Authentication] > [Consent Items] on the app management page.

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 server redirects (HTTP 302) the result as a query string to the redirect_uri. The redirect URI must be one of the values registered in [App] > [Platform key] > [REST API key] > [Redirect URI] on the app management page.

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 Error code and handle the situation by displaying an appropriate service page or message to the user based on the cause of the error.

Business consent screen

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.

Request

Query parameters

Name	Type	Description	Required
client_id	`String`	Service app REST API key. Can be found in [App] > [Platform key] > [REST API key] on the app management page.	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 [App] > [Platform key] > [REST API key] > [Redirect URI] on the app management page.	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 [Business Authentication] > [Consent Items] on the app management page. 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. Important: When requesting authorization for the [Kakao Moment/Keyword Ads ad account creation] consent items, only entire ad accounts* can be requested. Depending on the service, the request must be sent in the `${ScopeGroup}:` format. (Example: `resource_ids=moment:&resource_ids=keyword:*`)	X*

* Required when scope includes keyword_create or moment_create.

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
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	REST API key Switch to a Biz app Set Business redirect URI Business consent items	Required	Required

Issues 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 Error code for details.

Default activation of Client secret for REST API key

For service security, the REST API key (including the key automatically created with the app) is added with the Client secret feature enabled by default. Therefore, you must include the client_secret parameter in your token issuance requests. If necessary, you can disable this feature.

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 in [App] > [Platform key] > [REST API key] on the app management page.	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 [App] > [Platform key] > [REST API key] > [Redirect URI] on the app management page.	O
client_secret	`String`	The Client secret code used for additional verification to enhance security when issuing a token. Can be configured in [App] > [Platform key] > [REST API key] on the app management page. Required when the setting is [ON].	X

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}" \
  -d "client_secret=${CLIENT_SECRET}"

Response

HTTP/1.1 200
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	-	-

Verifies 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 Error code 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 Kakao Talk 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	-	-

Retrieves 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 Error code 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	-	-

Revokes 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 Error code 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}"
}

사이드 메뉴

Docs Home

Getting started

Kakao Developers

Login

Communication

Kakao Map

Navigation

Advertisement

Search

More

REST API

Get business authorization code

Basic information

Request

Query parameters

Response

Query parameters

Sample

Request

Request: All Kakao Moment ad accounts of the user

Request: Specific Kakao Moment ad account of the user

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

Request: User selects directly

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

Get business token

Basic information

Request

Header

Body

Response

Body

Sample

Request

Response

Retrieve business token information

Basic information

Request

Header

Response

Body

BizAgreement

Sample

Request

Response

Retrieve business user information

Basic information

Request

Header

Response

Body

Sample

Request

Response: Including user's email information

Revoke business token

Basic information

Request

Header

Response

Body

Sample

Request

Response

Was this helpful?

REST API

Get business authorization code

Get business token

Retrieve business token information

Retrieve business user information

Revoke business token