KAPI 패시브 연동

이 문서는 KAPI 패시브 연동 방법을 안내합니다. 이 문서의 내용은 KAPI 패시브 연동으로 카카오 API 플랫폼에 API를 제공하기로 협의한 사용처에만 유효합니다. API 제공을 위해 해야 할 일을 함께 참고합니다.

패시브 연동 API 처리 과정

KAPI 패시브 연동으로 제공하는 제공자 API의 요청 처리 과정을 안내합니다.

패시브 연동 방식 API 요청 처리 과정

API 사용자가 사용자 앱의 앱 키로 API를 요청합니다.
API 제공자가 제공자 앱의 어드민 키로 패시브 연동 API를 호출합니다.
API 제공자는 카카오 API 플랫폼이 전달하는 패시브 연동 API의 응답을 반영해 API 요청을 처리한 후, 사용자에게 API 응답을 반환합니다.

패시브 연동 API 정보 전달

API를 KAPI 패시브 연동으로 제공하려면, API 제공자는 [서비스] API플랫폼 아지트로 아래의 정보를 전달해야 합니다.

API 연동에 필요한 정보
API 식별 정보: API 사용자가 호출하는 API의 정보
- 도메인(Domain, 예: http://kapi.kakao.com)
- 메서드(Method, 예: POST)
- 경로(Path, 예: /v2/internal/user/me)
사용할 인증 방식
제공할 상태 확인 API 정보

패시브 연동 API

기본 정보

메서드	URL	인증 방식
`POST`	카카오 `http://kapi.kakao.com/v2/internal/passive/authorize` 공동체 `https://kapi.kakao.com/v2/internal/passive/authorize`	API 제공자 앱 어드민 키

권한	사전 설정	카카오 로그인	동의항목
필요: 공동체 앱	어드민 키 API 제공을 위해 해야 할 일	-	-

패시브 연동한 API 제공자가 사용자에게 API 요청을 받은 경우 호출해야 하는 API입니다. 이 API는 앱과 사용자 인증, 권한 및 쿼터 확인, 통계를 위한 데이터 수집을 처리합니다.

헤더에 API 제공자 앱의 어드민 키(API_PROVIDER_APP_ADMIN_KEY)를 담아 POST로 요청합니다. 사용하는 인증 방식에 따라 요청 본문의 구성이 다릅니다. 아래 인증 방식별 본문 설명을 확인합니다.

앱 인증
앱과 사용자 인증
앱과 비즈니스 인증

요청 성공 시 응답은 API 사용자 앱의 정보를 포함합니다. 요청 실패 시 에러 코드로 원인을 확인합니다. 사용자에게 안내가 필요한 에러 발생 시, 에러 처리를 참고해 API 사용자에 적절한 에러 응답을 반환해야 합니다.

요청

헤더

이름	설명	필수
Authorization	`Authorization: KakaoAK ${API_PROVIDER_APP_ADMIN_KEY}` 인증 방식, API 제공자 앱 어드민 키로 인증 요청	O
Content-Type	`Content-Type: application/x-www-form-urlencoded;charset=utf-8` 요청 데이터 타입	O

본문: 공통

사용하는 인증 방식에 상관 없이 공통으로 포함해야 하는 파라미터 목록입니다.

이름	타입	설명	필수
path	`String`	협의 시 전달한 API 식별 정보의 경로 (예: `/v2/internal/user/me`)	O
domain	`String`	협의 시 전달한 API 식별 정보의 도메인 (예: `http://kapi.kakao.com`) 중요: 협의 시 전달한 페이즈(Phase)의 도메인만 포함 가능	X
method	`String`	협의 시 전달한 API 식별 정보의 메서드	X
target_kakao_agent	`String`	KA 헤더 형식의 API 사용자 추가 정보, 사용자의 API 호출 방식에 따라 아래 항목 필수 포함 필요 Native 앱 키: `os`, `origin` (제공자 자체 SDK를 사용하는 경우 한정, Kakao SDK 사용 시 자동으로 요청에 포함) JavaScript 키: `os`, `origin`, `ip` REST API 키 또는 앱과 비즈니스 인증: `ip` 중요: API 제공자 서버에서 REST API로 패시브 연동 API를 호출할 경우, 요청 방식에 상관없이 API 사용자의 `ip` 포함 필요 참고: 보안: 호출 허용 IP 주소	O
operation	`String`	수행할 쿼터 동작, 아래 중 하나(기본값: `increase`) `increase`: 사용량 1 증가 `decrease`: 사용량 1 감소 `add`: `operand` 값을 사용량에 추가 `check`: `operand` 값을 사용량에 추가했을 경우의 결과 확인, 쿼터 초과 여부 확인 시 사용	X
operand	`Integer`	`operation`을 `add` 또는 `check`로 지정한 경우 적용할 사용량(기본값: `1`), 쿼터 소모량이 유동적인 경우 사용	X

본문: 앱 인증

앱 인증 방식 사용 시 본문: 공통에 추가로 포함해야 하는 파라미터 목록입니다.

API 사용자를 지정하기 위해 아래 중 하나의 파라미터는 필수로 포함해야 합니다.
- target_app_key
- target_app_id

이름	타입	설명
target_app_key	`String`	API 사용자의 앱 키
target_app_id	`Integer`	API 사용자의 앱 ID

본문: 앱과 사용자 인증

앱과 사용자 인증 방식 사용 시 본문: 공통에 추가로 포함해야 하는 파라미터 목록입니다.

API 사용자를 지정하기 위해 아래 중 한 가지 파라미터 조합을 필수로 포함해야 합니다.
- target_app_key, target_id, target_id_type
- target_app_id, target_id, target_id_type
- target_access_token

이름	타입	설명
target_app_key	`String`	API 사용자의 앱 키
target_app_id	`Integer`	API 사용자의 앱 ID
target_access_token	`String`	API 사용자 앱의 액세스 토큰
target_id	`String`	`target_id_type`에 해당하는 API 사용자 ID
target_id_type	`String`	`target_id`의 ID 종류, 아래 중 하나 `user_id`: 회원번호 `account_id`: 카카오계정 ID `talk_id`: 카카오톡 회원번호

본문: 앱과 비즈니스 인증

앱과 비즈니스 인증 방식 사용 시 본문: 공통에 추가로 포함해야 하는 파라미터 목록입니다.

API 사용자와 비즈니스 자산을 지정하기 위해 아래 중 한 가지 파라미터 조합을 필수로 포함해야 합니다.
- target_access_token
- target_access_token, target_ad_account_id
- target_access_token, target_channel_public_id

이름	타입	설명
target_access_token	`String`	API 사용자 앱의 비즈니스 토큰
target_ad_account_id	`Integer`	API 사용자의 광고계정 ID
target_channel_public_id	`String`	API 사용자의 카카오톡 채널 프로필 ID

응답

본문

아래 외에도 제공자 요청 응답 필드가 포함될 수 있습니다.

이름	타입	설명
app	`AppDetailInfo`	API 사용자 앱 정보
user	`UserInfo`	API 사용자 정보
api	`APIInfo`	API 설정 정보

AppDetailInfo

이름	타입	설명
id	`Integer`	API 사용자 앱의 ID
type	`String`	API 사용자 앱 타입, 아래 중 하나 `DEFAULT`: 일반 앱 `SAMPLE`: 샘플 앱 `KAKAO`: 인하우스 앱 `PARTNER`: 공동체 앱 `DAUM`: 다음 앱 `GAME`: 게임 앱 참고: 카카오디벨로퍼스 앱 타입
name	`String`	API 사용자 앱의 이름
company	`String`	API 사용자 앱의 회사명
status	`String`	API 사용자의 앱 상태, 아래 중 하나 `ACTIVE`: 활성 `BLOCKED`: 차단
category	`String`	API 사용자 앱의 카테고리
owner_developer	`DeveloperInfo`	API 사용자 앱의 소유자(OWNER)인 개발자 정보
app_key	`String`	API 사용자 앱의 앱 키 요청 파라미터별 응답 `target_app_key`로 요청 시, 해당 앱 키 `target_access_token`으로 요청 시, 해당 토큰 발급에 사용한 앱 키 `target_app_id`로 요청 시, REST API 키(제공자 앱이 사용자 앱의 앱 키를 조회할 수 있는 응답 권한을 보유한 경우)
app_key_type	`String`	`app_key`의 타입, 아래 중 하나 `NATIVE_APP_KEY` `REST_API_KEY` `JAVASCRIPT_KEY` `ADMIN_KEY` 요청 파라미터별 응답: `app_key`와 동일
app_keys	`AppKey[]`	API 사용자 앱의 앱 키 목록 요청 파라미터별 응답 `target_app_key`로 요청 시, 해당 앱 키와 REST API 키를 포함 `target_access_token`으로 요청 시, 해당 액세스 토큰 발급에 사용한 앱 키와 REST API 키를 포함 `target_app_id`로 요청 시, REST API 키를 포함 제공 조건: 제공자 앱이 사용자 앱의 앱 키를 조회할 수 있는 응답 권한 보유
app_business_info	`AppBusinessInfoResult`	API 사용자 앱의 비즈니스 정보

DeveloperInfo

이름	타입	설명	필수
id	`Integer`	개발자 ID	O
account_id	`Integer`	개발자의 카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유	X
registered_at	`String`	개발자 가입 시각(RFC3339 internet date/time 형식)	O
deactivated	`Boolean`	개발자 계정이 휴면 계정 탈퇴 처리로 탈퇴된 경우, 서비스에 영향을 주기 않기 위해 탈퇴된 상태로 소유자(OWNER) 정보가 남으며, 이 경우에만 `true`로 응답 개발자 계정이 휴면 계정 탈퇴 처리로 탈퇴되어, 서비스 유지를 위한 소유자(OWNER) 정보만 남은 상태인 경우 `true`로 응답	O

AppKey

이름	타입	설명
app_key	`String`	조회 대상 앱의 앱 키
app_key_type	`String`	`app_key`의 타입, 아래 중 하나 `NATIVE_APP_KEY` `REST_API_KEY` `JAVASCRIPT_KEY` `ADMIN_KEY`
is_target_app_key_type	`Boolean`	`app_key`와 `target_app_key`의 앱 키 타입 일치 여부 `true`: 일치 `false`: 불일치

UserInfo

이름	타입	설명
user_id	`Long`	회원번호 제공 조건: 앱과 사용자 인증 방식으로 요청한 경우
account_id	`Integer`	카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한을 보유한 API 제공자 앱이 앱과 사용자 인증 방식으로 요청한 경우
user_status	`String`	사용자와 사용자 앱의 연결 상태, 아래 중 하나 `REGISTERED`: 연결 `PREREGISTERED`: 연결 대기 `NONE`: 연결 없음
biz_agreements	`BizAgreement[]`	사용자가 동의한 비즈니스 동의항목 정보 목록 제공 조건: 앱과 비즈니스 인증 방식으로 요청한 경우

APIInfo

이름	타입	설명
review_type	`String`	사용자 앱의 API 사용 권한 보유 여부, 아래 중 하나 `NONE`: 사용 권한이 필요 없는 API를 요청한 경우 `REVIEWED`: 이미 API 사용 권한을 보유한 경우 `UNREVIEWED`: 사용 권한은 없지만 테스트를 위한 제한적 사용이 가능한 경우

AppBusinessInfoResult

이름	타입	설명	필수
biz_app	`Boolean`	비즈앱 여부	O
biz_plus_friends_app	`Boolean`	비즈니스 채널이 연결된 앱인지 여부	O
business_number	`String`	사업자 번호	X

예제

예제: 앱 인증 방식

파라미터
- API 사용자 앱 키(target_app_key): JavaScript 키
- API 식별 정보: path, domain, method
- KA 헤더 형식의 API 사용자 추가 정보(target_kakao_agent): IP

curl -v -X POST "http://kapi.kakao.com/v2/internal/passive/authorize" \
  -H "Authorization: KakaoAK ${API_PROVIDER_APP_ADMIN_KEY}" \
  -d "target_app_key=${API_CALLER_APP_JAVASCRIPT_KEY}" \
  --data-urlencode "target_kakao_agent=ip/${API_CALLER_SERVER_IP}" \
  --data-urlencode "path=${PATH}" \
  --data-urlencode "domain=${DOMAIN}" \
  --data-urlencode "method=${METHOD}"

예제: 앱과 사용자 인증 방식

파라미터
- 사용자 액세스 토큰(target_access_token)
- API 식별 정보: path, domain, method
- KA 헤더 형식의 API 사용자 추가 정보(target_kakao_agent): IP

curl -v -X POST "http://kapi.kakao.com/v2/internal/passive/authorize" \
  -H "Authorization: KakaoAK ${API_PROVIDER_APP_ADMIN_KEY}" \
  -d "target_access_token=${ACCESS_TOKEN}" \
  --data-urlencode "target_kakao_agent=ip/${API_CALLER_SERVER_IP}" \
  --data-urlencode "path=${PATH}" \
  --data-urlencode "domain=${DOMAIN}" \
  --data-urlencode "method=${METHOD}"

예제: 앱과 비즈니스 인증 방식

파라미터
- 비즈니스 토큰: target_access_token
- API 식별 정보: path, domain, method
- KA 헤더 형식의 API 사용자 추가 정보(target_kakao_agent): IP
- 광고계정 ID(target_ad_account_id) 또는 채널 공개 ID(target_channel_public_id) 중 하나

curl -v -X POST "http://kapi.kakao.com/v2/internal/passive/authorize" \
  --header "Authorization: KakaoAK ${API_PROVIDER_APP_ADMIN_KEY}" \
  --data-urlencode "target_access_token=${BUSINESS_ACCESS_TOKEN}" \
  --data-urlencode "target_kakao_agent=ip/${API_CALLER_SERVER_IP}" \
  --data-urlencode "path=${PATH}" \
  --data-urlencode "domain=${DOMAIN}" \
  --data-urlencode "method=${METHOD}" \
  --data-urlencode "target_ad_account_id=123" \
  --data-urlencode "target_channel_public_id=_abc" \

응답: API 사용자 앱 키로 앱 인증 요청

{
  "app": {
    "id": 977071,
    "name": "Sample",
    "company": "SampleCompany",
    "type": "DEFAULT",
    "status": "ACTIVE",
    "category": "Book_Reference",
    "owner_developer": {
      "id": 576952,
      "registered_at": "2022-05-03T05:38:36Z",
      "deactivated": false,
      "account_id": 2137162
    },
    "app_keys": [
      {
        "app_key": "${API_CALLER_APP_KEY}",
        "app_key_type": "${API_CALLER_APP_KEY_TYPE}",
        "is_target_app_key_type": true
      }
    ]
  },
  "api": {
    "review_type": "NONE"
  }
}

응답: 액세스 토큰으로 앱과 사용자 인증 요청

{
  "app": {
    "id": 977071,
    "name": "Sample",
    "company": "SampleCompany",
    "type": "DEFAULT",
    "status": "ACTIVE",
    "category": "Book_Reference",
    "owner_developer": {
      "id": 576952,
      "registered_at": "2022-05-03T05:38:36Z",
      "deactivated": false,
      "account_id": 2137162
    },
    "app_key": "${API_CALLER_APP_KEY}",
    "app_key_type": "${API_CALLER_APP_KEY_TYPE}",
    "app_keys": [
      {
        "app_key": "${API_CALLER_APP_KEY}",
        "app_key_type": "${API_CALLER_APP_KEY_TYPE}",
        "is_target_app_key_type": true
      }
    ]
  },
  "user": {
    "id": 1134566789999,
    "status": "REGISTERED",
    "account_id": 98765 // 응답 권한 필요
  },
  "api": {
    "review_type": "NONE"
  }
}

응답: 비즈니스 토큰으로 앱과 사용자 인증 요청

{
  "app": {
    "id": 977071,
    "name": "Sample",
    "company": "SampleCompany",
    "type": "DEFAULT",
    "status": "ACTIVE",
    "category": "Book_Reference",
    "owner_developer": {
      "id": 576952,
      "registered_at": "2022-05-03T05:38:36Z",
      "deactivated": false,
      "account_id": 2137162
    },
    "app_key": "${API_CALLER_APP_KEY}",
    "app_key_type": "${API_CALLER_APP_KEY_TYPE}",
    "app_keys": [
      {
        "app_key": "${API_CALLER_APP_KEY}",
        "app_key_type": "${API_CALLER_APP_KEY_TYPE}",
        "is_target_app_key_type": true
      }
    ]
  },
  "user": {
    "account_id": 98765,
    "biz_agreements": [
      {
        "group": "moment",
        "scope": ["moment_management"],
        "ad_account_ids": ["*"]
      },
      {
        "group": "easy_message",
        "scope": ["easy_message_management"],
        "ad_account_ids": ["1111"],
        "channel_profile_ids": ["_abc"]
      }
    ]
  },
  "api": {
    "review_type": "NONE"
  }
}

인증 방식

앱 인증

패시브 연동 API로 앱 인증 요청 시, 카카오 API 플랫폼이 확인하는 항목입니다.

이름	설명
앱 정보	사용자 앱의 정보 확인, 잘못된 앱 정보 전달 시 `-401` 에러 반환 에러 반환 시 아래 항목 확인 권장 API 사용자 앱의 존재 여부 `target_kakao_agent` 파라미터의 KA 헤더 정보가 사용자 앱과 일치하는지 여부
권한	사용자 앱이 API 사용에 필요한 권한을 갖고 있는지 확인, 권한 미보유 시 `-5` 에러 반환
쿼터	사용자 앱의 쿼터 정보 확인 쿼터 정보가 올바르지 않은 경우 `-2` 에러 반환 쿼터를 초과한 경우 `-10` 에러 반환

앱과 사용자 인증

패시브 연동 API로 앱과 사용자 인증 요청 시, 카카오 API 플랫폼은 앱 인증 항목과 함께 아래 항목을 추가로 확인합니다.

이름	설명
사용자 인증	사용자 카카오계정과 `target_access_token`의 유효성 확인, 유효하지 않은 경우 `-401` 에러 반환
동의항목	사용자가 제공자 API의 필요 동의항목에 동의했는지 확인, 동의하지 않은 경우 `-402` 에러 반환
연결 상태	사용자와 사용자 앱 간 연결(`REGISTERED`) 여부 확인, 연결 대기(`PREREGISTERED`) 또는 미연결(`NONE`) 상태인 경우 `-401` 에러 반환 참고: 연결 상태

앱과 비즈니스 인증

패시브 연동 API로 앱과 비즈니스 인증 요청 시, 카카오 API 플랫폼은 앱 인증 항목과 함께 아래 항목을 추가로 확인합니다.

이름	설명
사용자 인증	사용자 카카오계정과 `target_access_token`의 유효성 확인, 유효하지 않은 경우 `-401` 에러 반환
비즈니스 자산	사용자가 제공자 API의 필요 비즈니스 자산에 동의했는지 확인, 동의하지 않은 경우 `-402` 에러 반환
동의항목	사용자가 제공자 API의 필요 동의항목에 동의했는지 확인, 동의하지 않은 경우 `-402` 에러 반환

참고: 요청 헤더

API 사용자로부터 인증 정보를 전달받는 요청 헤더는 지정된 형식을 준수해야 합니다. 아래 인증 정보별 헤더 형식과 예제를 참고합니다.

액세스 토큰: Authorization: Bearer ${ACCESS_TOKEN} 형식
앱 키: Authorization : KakaoAK ${APP_KEY} 형식(앱 키 종류와 무관)

# 액세스 토큰
curl -X POST "${URI}" \
  --header "Authorization: Bearer ${ACCESS_TOKEN}"
# ...

# 앱 키
curl -X POST "${URI}" \
  --header "Authorization : KakaoAK ${APP_KEY}"
# ...

참고: 인증 없음

카카오디벨로퍼스에 앱을 등록하지 않은 API 사용자에게 API를 제공해야 하는 경우, 별도의 인증 없이 패시브 연동 API를 호출하는 방법을 안내합니다.

인증 사용 권장

인증을 사용한 패시브 연동을 권장합니다. 인증 없이 패시브 연동 시 API 사용자의 정보를 알 수 없고, 다양한 플랫폼 기능도 사용할 수 없습니다.

메서드, URL, 인증 방식은 패시브 연동 API와 동일합니다.

요청 시 필수 파라미터는 path와 target_kakao_agent입니다. target_kakao_agent에는 카카오 API 플랫폼과 사전 협의한 origin 값을 반드시 포함해야 합니다. 자세한 파라미터별 설명은 패시브 연동 API 내용을 참고합니다.

요청 성공 시 응답은 본문 없이 HTTP 상태 코드 200 OK 입니다. 요청 실패 시 에러 코드로 원인을 확인합니다.

에러 처리

API 제공자는 에러 코드로 패시브 연동 API에서 발생하는 에러의 원인을 파악할 수 있습니다. 에러 발생 시 사용자에게 세부 내용을 에러 응답으로 전달해 문제를 해결한 후 재요청할 수 있도록 해야합니다. 아래 상황별 세부 내용을 확인합니다.

인증 에러

원인: 사용자의 앱 또는 정보가 유효하지 않은 경우

사용자의 앱, 플랫폼, 사용자 인증에 실패한 경우

// HTTP/1.1 401 Unauthorized
{
  "code": -401,
  "msg": "Invalid token" // 인증 실패 원인별 에러 메시지
}

존재하지 않는 사용자이거나, 사용자와 앱 간의 연결 상태가 조건을 만족하지 않는 경우

// HTTP/1.1 401 Unauthorized
{
  "code": -101,
  "msg": "NotRegisteredUser"
}

사용자가 휴면, 탈퇴 상태인 경우

// HTTP/1.1 400 Bad Request
{
  "code": -103,
  "msg": "the account is inactive."
}

사용자가 제재 상태인 경우

// HTTP/1.1 403 Forbidden
{
  "code": -4,
  "msg": "the account is blocked."
}

인가 에러

원인: 사용자 앱의 권한이나 동의항목이 필요한 경우 발생, 동의항목은 동의항목 추가 동의 요청으로 사용자에게 추가 동의 요청 가능

사용자 앱이 API를 사용할 수 없는 앱 타입인 경우

// HTTP/1.1 403 Forbidden
{
  "code": -5,
  "msg": "This app(12345:톡클라우드플랫폼앱) can not be a delegator app for target app(67890:톡클라우드서비스앱) or target api(DRIVE_BACKUP)"
}

사용자 앱에 API 사용 권한이 없는 경우

// HTTP/1.1 403 Forbidden
{
  "code": -5,
  "msg": "permission denied"
}

사용자 앱에 API 사용 시 필요한 동의항목이 설정되지 않은 경우

// HTTP/1.1 403 Forbidden
{
  "code": -3,
  "msg": "${APP_NAME} App disabled [talk_chats] scopes for [TALK_CHAT_LIST] API on developers.kakao.com. Enable it first."
}

API 사용 시 필요한 동의항목에 사용자가 동의하지 않은 경우

// HTTP/1.1 403 Forbidden
{
  "code": -402,
  "msg": "insufficient scopes., code=-402, api_type=EMOTICON_ITEMS, required_scopes=[emoticon], allowed_scopes=[talk_message, profile]"
}

쿼터 에러

원인: API 사용자가 쿼터를 초과해 요청한 경우(참고: API 쿼터 설정)

쿼터 초과

// HTTP/1.1 400 Bad Request
{
  "msg": "API limit has been exceeded.",
  "code": -10,
  "rule_id": 235,
  "rule_desc": "대행사 개발자계정으로 인증서 checkquota 요청 차단. targetAgency.ownerDeveloperId로 차단",
  "rule_name": "[인증서] 대행사 앱 개발자계정 차단"
}

사이드 메뉴

오픈 문서

시작하기

카카오디벨로퍼스

로그인

커뮤니케이션

인공지능

플랫폼 API

API 제공

전용 API

어드민 API

더 보기