이 문서는 REST API를 사용한 비즈니스 인증 구현 방법을 안내합니다.
이 문서에 포함된 기능 일부는 [도구] > [REST API 테스트]를 통해 사용해 볼 수 있습니다.
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://kauth.kakao.com/oauth/business/authorize |
- |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
비즈니스 동의 화면을 호출하고, 사용자 동의를 거쳐 비즈니스 인가 코드를 발급합니다. 비즈니스 동의 화면은 요청 시 지정한 비즈니스 동의항목에 대해 사용자에게 인가(동의)를 구합니다.
요청 시 서비스 앱 REST API 키와 인가를 요청할 비즈니스 동의항목 ID를 포함해야 합니다. 비즈니스 동의항목 ID는 비즈니스 동의항목 또는 [내 애플리케이션] > [비즈니스 인증] > [동의항목]에서 확인할 수 있습니다.
사용자는 비즈니스 동의 화면에서 동의 여부를 선택할 수 있습니다. 카카오 API 플랫폼은 사용자의 선택에 따라 요청 처리 결과를 담은 쿼리 스트링(Query string)을 redirect_uri
로 HTTP 302 리다이렉트(Redirect)합니다. Redirect URI는 [내 애플리케이션] > [비즈니스 인증] > [Redirect URI]에 등록된 값 중 하나여야 합니다.
서비스 서버는 redirect_uri
로 HTTP 302 리다이렉트된 요청의 Location에서 인가 코드 또는 에러를 확인해 다음과 같이 처리해야 합니다.
code
및 state
가 전달된 경우code
의 비즈니스 인가 코드 값으로 비즈니스 토큰 받기 API 요청error
및 error_description
이 전달된 경우비즈니스 동의 화면은 사용자의 기존 동의 여부와 상관없이 매 요청 시 마다 노출됩니다. 같은 동의 내역을 갖는 인가 코드로 비즈니스 토큰을 불필요하게 중복 발급하지 않도록 주의합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
client_id | String |
앱 REST API 키 [내 애플리케이션] > [앱 키]에서 확인 가능 |
O |
response_type | String |
code 로 고정 |
O |
redirect_uri | String |
비즈니스 인가 코드를 전달받을 서비스 서버의 URI [내 애플리케이션] > [비즈니스 인증] > [Redirect URI]에서 등록 |
O |
scope | String |
사용자에게 인가를 요청할 비즈니스 동의항목 ID 목록 동의항목 ID는 비즈니스 동의항목 또는 [내 애플리케이션] > [비즈니스 인증] > [동의항목]에서 확인 가능 쉼표(,)로 구분해 여러 개 전달 가능 비고: biz_account_email 만 단독 전달 불가, 다른 비즈니스 동의항목 ID와 함께 전달 필요비고: 광고계정 생성 동의항목( _create ) 인가 요청 시 ScopeGroup 에 해당하는 전체 광고계정을 대상으로 지정 필요(resource_ids 를 ScopeGroup:* 형태로 전달) |
O |
state | String |
비즈니스 인증 과정 중 동일한 값을 유지하는 임의의 문자열(정해진 형식 없음) Cross-Site Request Forgery(CSRF) 공격으로부터 비즈니스 인증 요청을 보호하기 위해 사용 각 사용자의 인증 요청에 대한 state 값은 고유해야 함인가 코드 요청, 인가 코드 응답, 토큰 발급 요청의 state 값 일치 여부로 요청 및 응답 유효성 확인 가능 |
X |
resource_ids | String[] |
인가를 요청할 사용자 비즈니스 자산 지정(기본값: 지정 안함, 사용자가 동의 화면에서 선택)ScopeGroup:ResourceId 형태로 여러 개 전달 가능, 아래 및 예제 참고ScopeGroup : 카카오 비즈니스 서비스 코드, 다음 중 하나- moment : 카카오모먼트- keyword : 키워드광고ResourceId : 비즈니스 자산 ID, * 전달 시 사용자 보유 비즈니스 자산 중 ScopeGroup 에 해당하는 전체 자산을 대상으로 요청비고: 광고계정 생성 동의항목( _create ) 인가 요청 시 ScopeGroup 에 해당하는 전체 광고계정을 대상으로 지정 필요(resource_ids 를 ScopeGroup:* 형태로 전달) |
X |
인가 코드 받기 요청의 응답은 HTTP 302 리다이렉트되어, redirect_uri
에 GET
요청으로 전달됩니다. 해당 요청은 아래와 같은 쿼리 파라미터를 포함합니다.
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
code | String |
비즈니스 토큰 받기 요청에 필요한 비즈니스 인가 코드 | X |
error | String |
인증 실패 시 반환되는 에러 코드 | X |
error_description | String |
인증 실패 시 반환되는 에러 메시지 | X |
state | String |
요청 시 전달한 state 값과 동일한 값 |
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}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kauth.kakao.com/oauth/business/token |
- |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
비즈니스 인가 코드로 비즈니스 토큰 발급을 요청합니다.
필수 파라미터를 포함해 POST
로 요청합니다. 요청 성공 시 응답은 비즈니스 토큰과 토큰 정보를 포함합니다. 비즈니스 토큰에 대한 자세한 정보는 비즈니스 토큰에서 확인할 수 있습니다. 요청 실패 시 문제 해결에서 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Content-type | Content-type: application/x-www-form-urlencoded;charset=utf-8 요청 데이터 타입 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
grant_type | String |
authorization_code 로 고정 |
O |
client_id | String |
앱 REST API 키 [내 애플리케이션] > [앱 키]에서 확인 가능 |
O |
code | String |
비즈니스 인가 코드 받기 API 요청으로 얻은 비즈니스 인가 코드 | O |
redirect_uri | String |
비즈니스 인가 코드가 리다이렉트된 URI [내 애플리케이션] > [비즈니스 인증] > [Redirect URI]에 등록한 값 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
token_type | String |
토큰 타입, bearer 로 고정 |
O |
access_token | String |
비즈니스 토큰 값 | O |
scope | String |
비즈니스 토큰에 할당된 비즈니스 동의항목 여러 개인 경우, 공백으로 구분 |
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"
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://kapi.kakao.com/v1/business/tokeninfo |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
- | - |
비즈니스 토큰의 유효성을 검증하거나 정보를 확인합니다.
비즈니스 토큰을 요청 헤더(Header)에 담아 GET
으로 요청합니다. 요청 성공 시 응답은 사용자의 비즈니스 인증 회원번호, 동의한 비즈니스 동의항목, 비즈니스 토큰 상태를 포함합니다. 요청 실패 시 문제 해결에서 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | String |
비즈니스 토큰 ID | O |
token_user_id | String |
사용자의 비즈니스 인증 회원번호 | O |
biz_agreements | BizAgreement[] |
사용자가 동의한 비즈니스 동의항목 정보 목록 | O |
status | String |
비즈니스 토큰 상태, active 로 고정 |
O |
updated_at | Datetime |
비즈니스 토큰의 최근 변경 일시, UTC | O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
group | String |
비즈니스 동의항목 종류, 다음 중 하나PERSONAL : 개인정보MOMENT : 카카오모먼트KEYWORD : 키워드광고 |
O |
scope | String[] |
사용자가 동의한 비즈니스 동의항목 ID 목록 | O |
ad_account_ids | String[] |
접근 권한이 있는 광고계정 ID 목록, 값이 * 인 경우 group 내 사용자가 소유한 전체 광고계정의 접근 권한 보유 |
X |
channel_public_ids | String[] |
접근 권한이 있는 카카오톡 채널 프로필 ID 목록 | 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"
}
메서드 | URL | 인증 방식 |
---|---|---|
GET |
https://kapi.kakao.com/v1/business/userinfo |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
비즈니스 인증 사용자 정보를 불러옵니다.
사용자 비즈니스 토큰을 헤더(Header)에 담아 GET
으로 요청합니다. 요청 성공 시 응답은 사용자의 비즈니스 인증 회원번호, 이메일을 포함합니다. 요청 실패 시 문제 해결에서 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
token_user_id | String |
사용자의 비즈니스 인증 회원번호 | O |
String |
카카오계정 대표 이메일 필요한 비즈니스 동의항목: 카카오계정(이메일) 비고: 이메일 사용 시 주의사항 |
X | |
email_verified | Boolean |
카카오계정 대표 이메일의 인증 및 유효 여부true : 인증된 유효 이메일false : 미인증 또는 다른 카카오계정에서 사용 중인 유효하지 않은 이메일 |
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
}
메서드 | URL | 인증 방식 |
---|---|---|
POST |
https://kapi.kakao.com/v1/business/revoke |
비즈니스 토큰 |
권한 | 사전 설정 | 비즈니스 인증 | 비즈니스 동의항목 |
---|---|---|---|
필요: 사용 권한 신청 | 비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목 |
필요 | 필요 |
발급된 비즈니스 토큰을 만료시킵니다.
비즈니스 토큰을 요청 헤더(Header)에 담아 POST
로 요청합니다. 요청 성공 시 응답은 만료된 비즈니스 토큰 ID와 사용자의 비즈니스 인증 회원번호를 포함합니다. 요청 실패 시 문제 해결에서 사유를 확인합니다.
이름 | 설명 | 필수 |
---|---|---|
Authorization | Authorization: Bearer ${BUSINESS_ACCESS_TOKEN} 인증 방식, 비즈니스 토큰으로 인증 요청 |
O |
이름 | 타입 | 설명 | 필수 |
---|---|---|---|
id | String |
비즈니스 토큰 ID | O |
token_user_id | String |
사용자의 비즈니스 인증 회원번호 | 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}"
}