페이지 이동경로

문서>
비즈니스 인증>
REST API

비즈니스 인증

REST API

이 문서는 REST API를 사용한 비즈니스 인증 구현 방법을 안내합니다.

이 문서에 포함된 기능 일부는 [도구] > [REST API 테스트]에서 사용해 볼 수 있습니다.

비즈니스 인가 코드 받기

기본 정보

메서드	URL	인증 방식
`GET`	`https://kauth.kakao.com/oauth/business/authorize`	-

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 Redirect URI 등록 비즈니스 동의항목	필요	필요

비즈니스 동의 화면을 호출해 비즈니스 인가 코드 발급을 요청합니다. 비즈니스 동의 화면은 요청 시 지정한 비즈니스 동의항목에 대해 사용자에게 인가(동의)를 구합니다.

서비스 앱 REST API 키를 담은 헤더와 비즈니스 동의항목 ID를 포함해 GET으로 요청합니다. 비즈니스 동의항목 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;charset=utf-8" \
    -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

BizAgreement

이름	타입	설명	필수
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 등록 비즈니스 동의항목	필요	필요

비즈니스 인증 사용자 정보를 요청합니다.

사용자 비즈니스 토큰을 헤더에 담아 GET으로 요청합니다. 요청 성공 시 응답은 사용자의 비즈니스 인증 회원번호, 이메일을 포함합니다. 요청 실패 시 문제 해결에서 사유를 확인합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: Bearer ${BUSINESS_ACCESS_TOKEN}` 인증 방식, 비즈니스 토큰으로 인증 요청	O

응답

본문

이름	타입	설명	필수
token_user_id	`String`	사용자의 비즈니스 인증 회원번호	O
email	`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 등록 비즈니스 동의항목	필요	필요

발급된 비즈니스 토큰을 만료시킵니다.

비즈니스 토큰을 요청 헤더에 담아 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}"
}

비즈니스 인증> REST API

비즈니스 인가 코드 받기
비즈니스 토큰 받기
비즈니스 토큰 정보 보기
비즈니스 사용자 정보 가져오기
비즈니스 토큰 발급 철회하기

menu

시작하기

로그인

커뮤니케이션

카카오맵

내비게이션

광고

검색

더 보기

비즈니스 인증

REST API

비즈니스 인가 코드 받기

기본 정보

요청

쿼리 파라미터

응답

쿼리 파라미터

예제

요청

요청: 사용자의 전체 카카오모먼트 광고계정

요청: 사용자의 특정 카카오모먼트 광고계정

요청: 사용자의 특정 카카오모먼트와 키워드광고 광고계정

요청: 사용자가 직접 선택

응답: 사용자가 [동의하고 계속하기] 선택, 비즈니스 인가 코드 발급

비즈니스 토큰 받기

기본 정보

요청

헤더

본문

응답

본문

예제

요청

응답

비즈니스 토큰 정보 보기

기본 정보

요청

헤더

응답

본문

BizAgreement

예제

요청

응답

비즈니스 사용자 정보 가져오기

기본 정보

요청

헤더

응답

본문

예제

요청

응답: 사용자의 이메일 정보 포함

비즈니스 토큰 발급 철회하기

기본 정보

요청

헤더

응답

본문

예제

요청

응답