비즈니스 인증

REST API

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

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

비즈니스 인가 코드 요청

기본 정보

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

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	REST API 키 비즈 앱 전환 비즈니스 인증 리다이렉트 URI 비즈니스 동의항목	필요	필요

비즈니스 동의 화면을 호출해 비즈니스 인가 코드 발급을 요청합니다.

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

서비스 앱 REST API 키를 담은 헤더와 비즈니스 동의항목 ID를 포함해 GET으로 요청합니다. 비즈니스 동의항목 ID는 비즈니스 동의항목 또는 앱 관리 페이지의 [비즈니스 인증] > [동의항목]에서 확인할 수 있습니다.

요청 성공 시 사용자에게 비즈니스 동의 화면을 표시합니다. 사용자는 해당 화면에서 동의항목의 동의 여부를 선택할 수 있습니다. 카카오디벨로퍼스는 사용자의 선택에 따라 요청 처리 결과를 담은 쿼리 문자열(Query string)을 redirect_uri로 HTTP 302 리다이렉트(Redirect)합니다. 리다이렉트 URI는 앱 관리 페이지의 [앱] > [플랫폼 키] > [REST API 키] > [리다이렉트 URI]에 등록된 값 중 하나여야 합니다.

서비스 서버는 redirect_uri로 HTTP 302 리다이렉트된 요청의 Location에서 인가 코드 또는 에러를 확인해 아래와 같이 처리해야 합니다.

code 및 state가 전달된 경우
- 인가 코드 발급 성공, code의 비즈니스 인가 코드 값으로 비즈니스 토큰 요청 API 호출
error 및 error_description이 전달된 경우
- 인가 코드 발급 실패, 에러 코드를 참고해 에러 원인별 상황에 맞는 서비스 페이지나 안내 문구를 사용자에게 보여주도록 처리

비즈니스 동의화면

비즈니스 동의 화면은 사용자의 기존 동의 여부와 상관없이 매 요청 시 마다 노출됩니다. 같은 동의 내역을 갖는 인가 코드로 비즈니스 토큰을 불필요하게 중복 발급하지 않도록 주의합니다.

요청

쿼리 파라미터

이름	타입	설명	필수
client_id	`String`	서비스 앱 REST API 키 앱 관리 페이지의 [앱] > [플랫폼 키] > [REST API 키]에서 확인 가능	O
response_type	`String`	`code`로 고정	O
redirect_uri	`String`	비즈니스 인가 코드를 전달받을 서비스 서버의 리다이렉트 URI 앱 관리 페이지의 [앱] > [플랫폼 키] > [REST API 키] > [리다이렉트 URI]에서 확인 가능	O
scope	`String`	사용자에게 인가를 요청할 비즈니스 동의항목 ID 목록 동의항목 ID는 비즈니스 동의항목 또는 앱 관리 페이지의 [비즈니스 인증] > [동의항목]에서 확인 가능 쉼표(,)로 구분해 여러 개 전달 가능 중요: `biz_account_email`만 단독 전달 불가, 다른 비즈니스 동의항목 ID와 함께 전달 필요 중요: [카카오모먼트/키워드광고 광고계정 생성] 동의항목 인가 요청 시 전체 광고계정만 요청 가능, 서비스에 따라 `${ScopeGroup}:` 형태로 전달 필요(예: `resource_ids=moment:`)	O
state	`String`	비즈니스 인증 과정 중 동일한 값을 유지하는 임의의 문자열(정해진 형식 없음) Cross-Site Request Forgery(CSRF) 공격으로부터 비즈니스 인증 요청을 보호하기 위해 사용 각 사용자의 인증 요청에 대한 `state` 값은 고유해야 함 인가 코드 요청, 인가 코드 응답, 토큰 발급 요청의 `state` 값 일치 여부로 요청 및 응답 유효성 확인 가능	X
resource_ids	`String[]`	인가를 요청할 사용자 비즈니스 자산 지정(기본값: 지정 안함, 사용자가 동의 화면에서 선택) `ScopeGroup:ResourceId` 형태로 여러 개 전달 가능, 아래 및 예제 참고 `ScopeGroup`: 카카오 비즈니스 서비스 코드, 아래 중 하나 `moment`: 카카오모먼트 `keyword`: 키워드광고 `ResourceId`: 비즈니스 자산 ID, `` 전달 시 사용자 보유 비즈니스 자산 중 `ScopeGroup`에 해당하는 전체 자산을 대상으로 요청 중요: [카카오모먼트/키워드광고 광고계정 생성] 동의항목 인가 요청 시 전체 광고계정만* 요청 가능, 서비스에 따라 `${ScopeGroup}:` 형태로 전달 필요 (예: `resource_ids=moment:&resource_ids=keyword:*`)	X*

* scope에 keyword_create 또는 moment_create 포함 시 필수

응답

인가 코드 요청의 응답은 리다이렉트(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_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_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_management,moment_delete

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

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

비즈니스 토큰 요청

기본 정보

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

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	REST API 키 비즈 앱 전환 비즈니스 인증 리다이렉트 URI 비즈니스 동의항목	필요	필요

비즈니스 인가 코드로 비즈니스 토큰 발급을 요청합니다.

헤더와 필수 파라미터를 포함해 POST로 요청합니다. 요청 성공 시 응답은 비즈니스 토큰과 토큰 정보를 포함합니다. 비즈니스 토큰에 대한 자세한 정보는 비즈니스 토큰에서 확인할 수 있습니다. 요청 실패 시 에러 코드에서 원인을 확인합니다.

REST API 키의 클라이언트 시크릿 기본 활성화

서비스의 보안을 위해 REST API 키(앱과 함께 자동 생성된 키 포함)는 클라이언트 시크릿 기능이 활성화된 상태로 추가됩니다. 따라서 토큰 발급 요청 시 client_secret를 포함해야 합니다. 부득이한 경우 비활성화할 수 있습니다.

요청

헤더

이름	설명	필수
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` 요청 데이터 타입	O

본문

이름	타입	설명	필수
grant_type	`String`	`authorization_code`로 고정	O
client_id	`String`	서비스 앱 REST API 키 앱 관리 페이지의 [앱] > [플랫폼 키] > [REST API 키]에서 확인 가능	O
code	`String`	비즈니스 인가 코드 요청으로 얻은 비즈니스 인가 코드	O
redirect_uri 앱 관리 페이지의 [앱] > [플랫폼 키] > [REST API 키] > [리다이렉트 URI]에서 확인 가능	`String`	비즈니스 인가 코드가 전달된 리다이렉트 URI	O
client_secret	`String`	토큰 발급 시, 보안을 강화하기 위해 추가 확인하는 클라이언트 시크릿 코드 앱 관리 페이지의 [앱] > [플랫폼 키] > [REST API 키]에서 설정 가능 [ON] 상태인 경우 필수로 요청에 포함해야 함	X

응답

본문

이름	타입	설명	필수
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}" \
  -d "client_secret=${CLIENT_SECRET}"

응답

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

비즈니스 토큰 정보 조회

기본 정보

메서드	URL	인증 방식
`GET`	`https://kapi.kakao.com/v1/business/tokeninfo`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 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`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 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`	비즈니스 토큰

권한	사전 설정	비즈니스 인증	비즈니스 동의항목
필요: 사용 권한 신청	비즈 앱 전환 비즈니스 인증 리다이렉트 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

비즈니스 인가 코드 요청

기본 정보

요청

쿼리 파라미터

응답

쿼리 파라미터

예제

요청

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

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

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

요청: 사용자가 직접 선택

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

비즈니스 토큰 요청

기본 정보

요청

헤더

본문

응답

본문

예제

요청

응답

비즈니스 토큰 정보 조회

기본 정보

요청

헤더

응답

본문

BizAgreement

예제

요청

응답

비즈니스 사용자 정보 조회

기본 정보

요청

헤더

응답

본문

예제

요청

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

비즈니스 토큰 발급 철회

기본 정보

요청

헤더

응답

본문

예제

요청

응답

도움이 되었나요?

REST API

비즈니스 인가 코드 요청

비즈니스 토큰 요청

비즈니스 토큰 정보 조회

비즈니스 사용자 정보 조회

비즈니스 토큰 발급 철회