사이드 메뉴
커뮤니케이션
API 제공
어드민 API
1회성 제공 동의
이 문서는 1회성 제공 동의 사용 방법을 안내합니다.
1회성 제공 동의는 사용자에게 1회성으로 특정 개인정보 제공 동의를 받아 카카오 API를 호출하기 위해 사용하는 단발성 인증 방법입니다. 1회성 제공 동의로 발급하는 OTP 토큰으로 일부 API를 호출할 수 있습니다.
아래는 1회성 제공 동의로 API를 호출하는 과정을 표현한 이미지입니다.

- OTP: 인가 코드 요청으로 사용자에게 1회성 제공 동의를 요청하고 인가 코드를 발급받습니다.
- 1의 결과로 발급받은 인가 코드로 OTP: 토큰 요청을 호출해 OTP 토큰을 발급받습니다.
- OTP 토큰으로 API를 호출해 필요한 개인정보 제공 또는 기능 수행을 요청합니다.
1회성 제공 동의는 아래와 같은 경우에 사용할 수 있습니다.
- 1회성으로 API 사용에 필요한 사용자 동의를 받으려는 경우
- 설문조사 등 특정 1회성 서비스를 회원 가입 없이 제공하려는 경우
- 이벤트 참여 등 특정 목적으로 추가 정보 제공에 일시적인 동의를 받으려는 경우
이 밖에도 설정에 따라 다양한 목적으로 1회성 제공 동의를 활용할 수 있습니다. 1회성 제공 동의 타입의 활용 예시를 참고합니다.
단, 아래와 같은 경우에는 1회성 제공 동의를 사용할 수 없습니다.
- 카카오로부터 제공 받은 개인정보를 서비스 회원 DB에 저장(회원가입)해 활용하려는 경우
- 서비스에서 사용자 정보를 지속적으로 이용하는 경우
- 필요한 동의항목의 종류가 유동적으로 변경될 수 있어 특정할 수 없는 경우
위와 같이 1회성 제공 동의를 사용할 수 없는 경우에는 카카오 로그인의 동의항목 등 다른 방법으로 서비스에서 자체적으로 사용자 동의를 받아야 합니다.
일반적인 카카오 로그인 사용자 동의와 1회성 제공 동의의 다른 점은 아래와 같습니다.
| 구분 | 카카오 로그인 | 1회성 제공 동의 |
|---|---|---|
| 발급되는 토큰 | 액세스 토큰 리프레시 토큰 | OTP 토큰 |
| 회원 가입 | 필요 | 불필요 |
| 앱 연결 | 앱과 사용자가 연결됨 | 앱과 사용자가 연결되지 않음 |
| 사용자 정보 제공 제한 | 사용자의 앱 연결 상태에 따라 일부 사용자 정보 제공 불가, 사용자 연결 상태에 따른 정보 제공 제한 참고 | 1회성 제공 동의를 지원하는 사용자 정보에 한해 제공 |
| 동의 유효기간 | 앱 연결 해제(탈퇴) 또는 별도의 동의 철회 시까지 | 설정된 토큰 만료시간 동안만 유효 토큰 최대 만료시간은 1회성 제공 동의 타입 참고 |
| 동의항목 | 앱 관리 페이지의 [카카오 로그인] > [동의항목]에서 설정 가능한 동의항목 사용 가능 | 목적에 따라 필요한 동의항목 별도 설정, 1회성 제공 동의 타입 참고 |
1회성 제공 동의는 앱 타입과 사용 목적에 따라 타입을 지정하며, 타입별로 사용할 수 있는 동의항목의 종류와 토큰 최대 만료 시간이 다릅니다. 1회성 제공 동의 타입의 종류는 아래와 같습니다.
| 타입 | 설명 | 동의항목 | OTP 토큰 만료 시간* |
|---|---|---|---|
DEFAULT | 범용적인 목적의 1회성 인증을 위한 타입 제공 목적, 제공 기간 안내 문구 개별 정의 가능 활용 예시: 고객 상담, 이벤트 참여, 상품 배송지 입력과 같은 1회성 개인정보 제공 및 동작에 대한 API 요청이 필요할 때 | 해당 앱의 동의항목 중 선택 가능 | 최대 2시간 |
DEFAULT_INHOUSE | 범용적인 목적의 1회성 인증을 위한 타입 제공 목적, 제공 기간 안내 문구 개별 정의 가능 DEFAULT 타입과 마찬가지로 범용적인 목적의 1회성 제공 동의가 필요하지만, 인하우스 앱인 플랫폼 서비스로 제공하는 각 서비스에 대해 위임 방식으로 요청하려는 경우 DEFAULT_INHOUSE 타입 적용DEFAULT_INHOUSE 타입 요청은 인하우스 앱으로만 가능중요: 플랫폼 서비스의 앱에 위임 권한이 필요하므로 사용 신청 시 서비스 앱, 플랫폼 앱의 정보를 각각 전달해야 함 활용 예시: DEFAULT 타입 활용 예시 참고 | 서비스 앱의 동의항목 중 선택 가능 | 최대 7일 |
SURVEY | 비즈폼 서베이 서비스를 위한 타입 요청 시 plugin_ext_id 파라미터로 전달된 값을 참고해 비즈폼 서베이에 등록된 서비스 약관을 조회하며, 1회성 제공 동의 화면에 해당 약관에 동의하는 기능 제공응답의 terms 필드에 동의한 약관 목록 제공활용 예시: 비즈폼 서베이에서 설문조사 참여자 정보를 1회성으로 조회하기 위해 사용 | 프로필 정보(닉네임/프로필 사진) 닉네임 프로필 사진 카카오계정(이메일) 카카오계정(전화번호) | 최대 90일 |
KET_EVENT | 캐시프렌즈 이벤트를 위한 타입 활용 예시: 카카오페이지 캐시프렌즈에서 광고주 카카오톡 채널과의 관계 조회 및 카카오톡 채널 친구 추가에 필요한 사용자 동의 및 API 호출을 위해 사용 | 카카오톡 채널 추가 상태 및 내역 | 최대 2시간 |
1회성 제공 동의를 지원하는 API는 요청 주체와 인증 정보 전달 방식에 따라 OTP 토큰 방식 또는 OTP 위임 방식으로 요청할 수 있습니다. 두 방식 모두 서비스 앱에서 발급받은 OTP 토큰으로 사용자의 1회성 제공 동의 정보를 확인하지만, API를 호출하는 앱과 OTP 토큰 전달 위치가 다릅니다.
| 구분 | OTP 토큰 방식 | OTP 위임 방식 |
|---|---|---|
| 요청 주체 | 서비스 앱 | 서비스 앱의 권한을 위임받은 플랫폼 앱 |
| 인증 헤더 | Authorization: OTP ${OTP_TOKEN} | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY} |
| OTP 토큰 전달 위치 | Authorization 헤더 | target_otp_token 파라미터 |
| 사용 가능한 API | 각 API별 지원 범위에 따름 | 내부 API 요청 시 사용 가능 |
| 사용 예 | 서비스 앱이 OTP 토큰을 직접 전달해 API 요청 | 카카오 내부 플랫폼이 서비스 앱을 대신해 요청하고, 서비스 앱의 OTP 토큰을 파라미터로 전달 |
1회성 제공 동의를 사용하려면 아래 순서로 사용 신청합니다.
참고: 앱
위 과정에는 카카오디벨로퍼스 앱이 반드시 필요합니다. 아직 앱이 없다면, 앱 설정 > 앱과 인하우스 앱을 참고해 새로운 앱을 등록해야 합니다.
서비스에서 1회성 제공 동의를 사용해 구현하려는 기능이 무엇인지에 따라, 필요한 사용자 정보나 동작을 제공하는 API가 무엇인지 확인합니다.
- 1회성 제공 동의 타입에 따라 제공 가능한 사용자 정보의 종류가 제한될 수 있습니다. 자세한 내용은 1회성 제공 동의 타입 표의 동의항목을 참고합니다.
- 일부 사용자 정보는 권한이 있어야 제공받을 수 있습니다. 해당 정보를 제공하는 API의 개발 문서를 참고합니다.
| 사용자 정보 | 동의항목 | API |
|---|---|---|
| 카카오계정 ID | - | 사용자 정보 조회 |
| 카카오톡 회원번호 | - | 사용자 정보 조회 |
| 프로필 정보(닉네임/프로필 사진) | 닉네임 프로필 사진 프로필 정보(닉네임/프로필 사진) | 사용자 정보 조회 |
| 이메일 | 카카오계정(이메일) | 사용자 정보 조회 |
| 유효 이메일 여부 | 카카오계정(이메일) | 사용자 정보 조회 |
| 이메일 인증 여부 | 카카오계정(이메일) | 사용자 정보 조회 |
| 이름 | 이름 | 사용자 정보 조회 |
| 성별 | 성별 | 사용자 정보 조회 |
| 연령대 | 연령대 | 사용자 정보 조회 |
| 출생연도 | 출생연도 | 사용자 정보 조회 |
| 생일 | 생일 | 사용자 정보 조회 |
| 전화번호 | 카카오계정(휴대전화번호) | 사용자 정보 조회 |
| 카카오계정 가입일자 | 카카오계정 가입일자 | 사용자 정보 조회 |
| CI(연계정보) | CI(연계정보) | 사용자 정보 조회 |
| 본인인증 받은 시각 | CI(연계정보) | 사용자 정보 조회 |
| 본인확인정보(이름) | 본인확인정보(이름) | 사용자 정보 조회 |
| 본인확인정보(생년월일) | 본인확인정보(생년월일) | 사용자 정보 조회 |
| 본인확인정보(성별) | 본인확인정보(성별) | 사용자 정보 조회 |
| 본인확인정보(내외국인) | 본인확인정보(내외국인) | 사용자 정보 조회 |
| 카카오톡 서비스 가입 여부 | 카카오톡 서비스 가입 여부 | 사용자 정보 조회 |
| 배송지정보(수령인명, 배송지 주소, 전화번호) | 배송지정보(수령인명, 배송지 주소, 전화번호) | 배송지 조회 |
| 카카오톡 채널 추가 상태 및 내역 | 카카오톡 채널 추가 상태 및 내역 | 카카오톡 채널 관계 조회 |
- 공동체의 경우, 아래 중 일부 API를 사용하려면 권한이 필요합니다. 권한을 참고합니다.
| API | 필요한 동의항목 | 설명 |
|---|---|---|
| 사용자 정보 조회 | 1회성 제공 동의를 지원하는 사용자 정보 참고 | 사용자가 1회성 제공 동의한 항목의 정보를 조회합니다. |
| 배송지 조회 Permission | 배송지정보(수령인명, 배송지 주소, 전화번호) | 사용자 카카오계정의 배송지 정보를 조회합니다. |
| 카카오톡 채널 친구 추가 Permission | 카카오톡 채널 추가 상태 및 내역 | 특정 카카오톡 채널을 사용자의 친구로 추가합니다. |
| 톡캘린더 일반 일정 삭제 Permission | 톡캘린더 및 일정 생성, 조회, 편집/삭제 | 사용자의 일반 일정을 삭제합니다. |
| 톡캘린더 공개 일정 사용자 캘린더에 추가 Permission | 톡캘린더 및 일정 생성, 조회, 편집/삭제 | 공개 일정을 사용자의 톡캘린더에 추가합니다. |
| 패시브 연동 Permission | - | OTP 토큰 인증이 필요한 경우에 사용합니다. |
[서비스] API플랫폼 아지트로 아래 정보를 전달합니다.
| 항목 | 설명 |
|---|---|
| 앱 이름과 ID | 앱 관리 페이지의 [대시보드]에서 확인 가능DEFAULT_INHOUSE 타입을 사용하려는 경우, 요청을 위임받은 플랫폼 앱의 정보도 함께 전달 |
| 필요한 동의항목과 API | 1회성 제공 동의 시 사용하려는 동의항목과 API 1. 요구 사항 검토 참고 |
| 사용 목적 | 필요한 동의항목과 API의 사용 시나리오 등 필요한 기능에 대한 설명 |
| 제공 목적 안내 문구 | 1회성 제공 동의의 동의 화면에 노출할 개인정보 수집 목적 안내 (예: " ${SERVICE_NAME} 서비스의 ${EVENT_NAME} 이벤트를 위해") |
| 제공 기간 안내 문구 | 1회성 제공 동의의 동의 화면에 노출할 개인정보 처리 안내 (예: "제공목적 달성 후 지체없이 파기") |
| 개인정보 처리방침 및 검토 의견 | 1회성 제공 동의로 제공받은 개인정보 처리방침 1회성 제공 동의를 사용하려는 기능에 대한 개인정보 검토 의견 |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| - | REST API 키 카카오 로그인 활성화 리다이렉트 URI 동의항목 | - | 필요: 서비스 가입 및 이용 시 필요한 사용자 정보 및 접근권한 |
사용자에게 1회성 제공 동의를 요청하는 동의 화면을 출력하고, OTP 토큰을 발급받기 위한 인가 코드를 발급받습니다. 요청 과정은 일반적인 카카오 로그인의 인가 코드 요청과 거의 동일하나, 1회성 제공 동의 요청에 필요한 파라미터를 추가 전달해야 하는 점에 주의합니다.
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| client_id | String | 서비스 앱 REST API 키 앱 관리 페이지의 [앱] > [플랫폼 키] > REST API 키에서 확인 가능 | O |
| redirect_uri | String | 인가 코드를 전달받을 리다이렉트 URI 앱 관리 페이지의 [앱] > [플랫폼 키] > [REST API 키] > [리다이렉트 URI]에서 확인 가능 중요: DEFAULT_INHOUSE 타입의 경우, 요청을 위임받은 플랫폼 앱에 redirect_uri 값이 등록되어 있어야 함 | O |
| response_type | String | code로 고정 | O |
| plugin | String | 앱에 설정된 1회성 제공 동의 타입, 아래 중 하나
| O |
| plugin_ext_id | Integer | 타입별 확장 키SURVEY 타입 전용 필수 파라미터요청 시 상황에 따라 타입의 기본 설정이 아닌 별도 설정을 적용하고자 할 때 사용 plugin_ext_id 파라미터 미사용 시, 동의항목 설정과 토큰 만료 시간은 타입별 기본 설정을 따름 | X* |
| delegate_client_id | String | DEFAULT_INHOUSE 타입 전용 필수 파라미터요청을 위임받은 플랫폼 앱의 REST API 키 | X* |
| ket_event_cpid | String | KET_EVENT 타입 전용 필수 파라미터사용자와의 관계를 확인할 카카오톡 채널의 프로필 ID 카카오톡 채널 추가 상태 및 내역 동의항목의 1회성 제공 동의로 해당 카카오톡 채널에 대한 카카오톡 채널 관계 조회 API 요청 가능 참고: 카카오톡 채널 프로필 ID 확인 방법 | X* |
| state | String | 로그인 요청과 웹훅 간에 상태를 유지하기 위해 사용되는 임의의 문자열(정해진 형식 없음) Cross-Site Request Forgery(CSRF) 공격으로부터 보호하기 위해 해당 파라미터 사용을 권장함 | X |
인가 코드 요청의 응답은 HTTP 302 리다이렉트되어, redirect_uri에 GET 요청으로 전달됩니다. 아래 쿼리 파라미터를 포함합니다.
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| code | String | OTP: 토큰 발급에 사용할 인가 코드 | O |
요청: DEFAULT 타입 요청
https://kauth.kakao.com/oauth/authorize?client_id=${SERVICE_APP_REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code&plugin=default&state=test
요청: DEFAULT_INHOUSE 타입 요청
https://kauth.kakao.com/oauth/authorize?client_id=${SERVICE_APP_REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code&plugin=default_inhouse&delegate_client_id=${DELEGATOR_APP_REST_API_KEY}&state=test
요청: KET_EVENT 타입 요청
https://kauth.kakao.com/oauth/authorize?client_id=${SERVICE_APP_REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code&plugin=ket_event&ket_event_cpid=_NzL&state=test
응답
HTTP/1.1 302Location: ${REDIRECT_URI}?code=${AUTHORIZATION_CODE}
인가 코드를 전달하고 OTP 토큰을 발급받습니다. 발급받은 OTP 토큰을 사용해 필요한 사용자 정보를 제공받거나 필요한 동작을 수행하는 API를 요청할 수 있습니다. 1회성 제공 동의를 지원하는 사용자 정보, 1회성 제공 동의를 지원하는 API를 참고합니다.
인가 코드와 함께 필수 파라미터를 포함해 POST로 요청합니다. 요청 성공 시 응답은 OTP 토큰 값과 만료 시간, 사용자가 1회성 제공 동의한 동의항목 목록을 포함합니다. OTP 토큰은 JSON Web Token(JWT) 규격으로 발급되며, Base64 URL-Safe 인코딩된 값입니다. OTP 토큰 값을 디코딩해 상세 정보를 확인할 수 있습니다.
OTP 토큰의 유효시간은 앱에 설정된 1회성 제공 동의 타입에 따라 다르므로, 1회성 제공 동의 타입을 참고합니다. OTP 토큰의 유효성을 검증하려면 OTP: 토큰 정보 조회 API를 사용합니다.
서비스의 보안을 위해 REST API 키(앱과 함께 자동 생성된 키 포함)는 클라이언트 시크릿 기능이 활성화된 상태로 추가됩니다. 따라서 토큰 발급 요청 시 client_secret를 포함해야 합니다. 부득이한 경우 해당 기능 안내를 참고해 비활성화할 수 있습니다.
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| grant_type | String | authorization_code로 고정 | O |
| client_id | String | 서비스 앱 REST API 키 앱 관리 페이지의 [앱] > [플랫폼 키] > REST API 키에서 확인 가능 | O |
| redirect_uri | String | 인가 코드가 전달된 리다이렉트 URI 앱 관리 페이지의 [앱] > [플랫폼 키] > [REST API 키] > [리다이렉트 URI]에서 확인 가능 중요: DEFAULT_INHOUSE 타입의 경우, 요청을 위임받은 플랫폼 앱에 redirect_uri 값이 등록되어 있어야 함 | O |
| code | String | 인가 코드 요청으로 얻은 인가 코드 | O |
| delegate_client_id | String | DEFAULT_INHOUSE 타입 전용 필수 파라미터요청을 위임받은 플랫폼 앱의 REST API 키 | X* |
| client_secret | String | 토큰 발급 시, 보안을 강화하기 위해 추가 확인하는 클라이언트 시크릿 코드 앱 관리 페이지의 [앱] > [플랫폼 키] > [REST API 키]에서 설정 가능 [ON] 상태인 경우 필수로 요청에 포함해야 함 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| access_token | String | 1회성 제공 동의로 발급받은 OTP 토큰 값, JWT 규격을 따름 BASE64 URL-Safe 인코딩 값으로, 디코딩해 토큰 상세 정보 확인 가능 아래 JWT Header, JWT Payload 표 참고 | O |
| token_type | String | otp로 고정 | O |
| expires_in | Integer | 토큰 만료 시간(초) | O |
| scope | String | 사용자가 1회성 제공 동의한 동의항목 여러 개일 경우, 공백으로 구분 사용자가 동의한 동의항목이 없을 경우, 응답에 scope 필드 미포함 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| typ | String | 토큰 타입 정보JWT로 고정 | O |
| alg | String | 토큰 암호화 알고리즘 정보HS256로 고정 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| aud | String | 앱 ID | O |
| sub | String | 암호화된 사용자 ID | O |
| scope | String[] | 사용자가 1회성 제공 동의한 동의항목 목록 사용자가 동의한 동의항목이 없을 경우 빈 배열로 JWT Payload에 포함됨 | O |
| iss | Integer | 토큰 발행처, https://kauth.kakao.com으로 고정 | O |
| exp | Integer | 토큰 만료 시간 | O |
| iat | Integer | 토큰 발급 시간 | O |
| pid | Integer | 앱의 1회성 제공 동의 설정 ID | X |
| terms | String[] | SURVEY 타입에 대한 요청의 응답에만 포함사용자가 동의한 서비스 약관 목록 | X |
| cpid | String | KET_EVENT 타입에 대한 요청의 응답에만 포함OTP: 인가 코드 발급 시 ket_event_cpid 파라미터로 전달한 카카오톡 채널 프로필 ID | X |
요청: DEFAULT 타입 요청
curl -v POST "https://kauth.kakao.com/oauth/token" \-H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \-d "grant_type=authorization_code" \-d "client_id=${SERVICE_APP_REST_API_KEY}" \-d "redirect_uri=${REDIRECT_URI}" \-d "code=${AUTHORIZATION_CODE}" \-d "client_secret=${CLIENT_SECRET}"
요청: DEFAULT_INHOUSE 타입 요청
curl -v POST "https://kauth.kakao.com/oauth/token" \-H "Content-Type: application/x-www-form-urlencoded;charset=utf-8" \-d "grant_type=authorization_code" \-d "client_id=${SERVICE_APP_REST_API_KEY}" \-d "redirect_uri=${REDIRECT_URI}" \-d "code=${AUTHORIZATION_CODE}" \-d "delegate_client_id=${DELEGATOR_APP_REST_API_KEY}" \-d "client_secret=${CLIENT_SECRET}"
응답
// HTTP/1.1 200{"access_token": "${OTP_TOKEN}","token_type": "otp","expires_in": 1199,"scope": "account_email profile_image gender profile_nickname shipping_address"}
응답: OTP 토큰 디코딩 예제
// JWT Header{"typ":"JWT","alg":"HS256"}// JWT Payload{"aud":"1134530","sub":"IZeosd7f7B2MhUatmLlJ8f-BiiV-B8M8_bpfpfvQ5KcYkJVBjKmj3-TPdZbOknLUZuY1NnWrUOiBboEVPqwlhxNaW_Ger2MJin3PT7qPaGM","scope":["gender","profile_nickname"],"iss":"https://kauth.kakao.com","exp":1633070439,"iat":1633069239,"pid":56}
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 카카오http://kapi.kakao.com/v1/internal/user/access_token_info공동체 https://kapi.kakao.com/v1/internal/user/access_token_info외부 https://kapi.kakao.com/v1/user/access_token_info | OTP OTP 위임 |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| 필요 | 어드민 키 카카오 로그인 활성화 | - | - |
카카오 로그인으로 발급받은 OTP 토큰의 정보를 조회합니다. OTP 토큰의 유효성을 검증하는 용도로 사용합니다. 자세한 안내는 토큰 정보 조회를 참고합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: OTP ${OTP_TOKEN}인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
- 내부 API 요청 시에만 사용 가능합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_otp_token | String | API 호출 서비스 앱의 OTP 토큰 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| expires_in | Long | 액세스 토큰의 만료 시간(단위: 초) | O |
| app_id | Int | 토큰이 발급된 앱 ID | O |
| account_id | Int | 카카오계정 ID 제공 조건: 카카오계정 ID 응답 권한 보유, 내부 API 요청 | X |
| scopes | String[] | 사용자가 동의한 동의항목 ID 목록 | O |
요청: OTP 토큰 방식
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/access_token_info" \-H "Authorization: OTP ${OTP_TOKEN}"
요청: OTP 토큰 방식
- 외부 API 요청
curl -v -G GET "https://kapi.kakao.com/v1/user/access_token_info" \-H "Authorization: OTP ${OTP_TOKEN}"
요청: OTP 위임 방식
- 파라미터
- OTP 토큰(
target_otp_token)
- OTP 토큰(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/access_token_info" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_otp_token=${OTP_TOKEN}"
응답: OTP 토큰 방식, 성공
{"scopes": ["account_email", "profile_image", "gender", "profile_nickname", "shipping_address"],"expires_in": 1089,"app_id": 208120,"account_id": 81825}
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET / POST | 카카오http://kapi.kakao.com/v2/internal/user/me공동체 https://kapi.kakao.com/v2/internal/user/me외부 https://kapi.kakao.com/v2/user/me | OTP OTP 위임 |
사용자가 1회성 제공 동의한 항목의 정보를 조회합니다. OTP 토큰으로 요청 시 1회성 제공 동의를 지원하는 사용자 정보에 한해 제공이 가능하며, 사용자가 각각의 필요한 동의항목에 동의해야만 응답에 값이 포함됩니다.
1회성 제공 동의 시에는 사용자와 앱이 연결되지 않으므로 회원번호(user_id)가 발급되지 않습니다. OTP 토큰으로 사용자 정보 조회를 요청한 경우에도 회원번호, 연결 시각과 같은 연결 관련 정보가 포함되지 않을 수 있습니다.
또한 OTP 토큰으로 요청할 경우에는 사용자가 1회성 제공 동의한 항목에 한해 정보를 제공하므로, 응답은 사용자 동의 필요 여부를 알리는 ${SCOPE}_needs_agreement 필드를 포함하지 않습니다. OTP 토큰 정보에 필요한 동의항목이 포함돼 있지 않을 경우, 다시 OTP: 인가 코드 요청부터 요청해 사용자로부터 1회성 제공 동의를 받아야 합니다.
헤더에 OTP 토큰을 담아 GET으로 요청합니다. property_keys 파라미터를 사용해 특정 사용자 정보 키를 지정해 조회할 수 있습니다. 성공 시 응답은 kakao_account 하위에 OTP 토큰의 scope에 해당하는 사용자 정보를 포함합니다. 자세한 안내는 사용자 정보 조회를 참고합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: OTP ${OTP_TOKEN}인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| secure_resource | Boolean | 이미지 URL 값의 HTTPS 반환 여부 (기본값: false) | X |
| property_keys | String[] | 응답에 포함할 정보의 키, 미지정 시 모든 정보 포함 키와 값의 쌍으로 구성 (예: ["id","properties.${CUSTOM_PROPERTY_KEY}","kakao_account.email"]) | X |
- 내부 API 요청 시에만 사용 가능합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
- OTP 위임 방식은 아래와 같은 경우에 사용합니다.
- OTP 토큰이 서비스로 제공하지 않고 카카오 내부 플랫폼에서 관리됨
- 카카오 내부 플랫폼이 서비스를 대신해 요청하고 서비스로 정보 전달
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_otp_token | String | API 호출 서비스 앱의 OTP 토큰 | O |
| secure_resource | Boolean | 이미지 URL 값의 HTTPS 반환 여부 (기본값: false) | X |
| property_keys | String[] | 응답에 포함할 정보의 키, 미지정 시 모든 정보 포함 키와 값의 쌍으로 구성 (예: ["id","properties.${CUSTOM_PROPERTY_KEY}","kakao_account.email"]) | X |
- 요청 시
property_keys파라미터로 조회할 정보를 지정한 경우, 응답은 해당 값만 제공
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| kakao_account | KakaoAccount | 카카오계정 정보 | X |
has_${FIELD_NAME}: Deprecated, 각 사용자 정보 값 소유 여부(Boolean), 해당 사용자 정보의 제공 가능 여부를 확인하는 용도로 사용할 수 없음(참고: needs_agreement)
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| profile | JSON | 프로필 정보 필요한 동의항목: 닉네임, 프로필 사진, 프로필 정보(닉네임/프로필 사진) | X |
| is_email_valid | Boolean | 이메일 유효 여부 유효한 이메일이라면 true(유효), 이메일이 다른 카카오계정에 사용돼 만료되었다면 false(무효)필요한 동의항목: 카카오계정(이메일) | X |
| is_email_verified | Boolean | 이메일 인증 여부, true(인증된 이메일) 또는 false(인증되지 않은 이메일)필요한 동의항목: 카카오계정(이메일) | X |
String | 카카오계정 대표 이메일 필요한 동의항목: 카카오계정(이메일) 중요: 이메일 사용 시 주의 사항 | X | |
| name | String | 카카오계정의 이름 본인인증된 실명이 있다면 해당 값 제공 실명과 일치하지 않을 수 있으니, 실명이 필요할 경우 본인확인정보(이름) 사용 권장 필요한 동의항목: 이름 | X |
| age_range | String | 연령대1~9: 1세 이상 10세 미만10~14: 10세 이상 15세 미만15~19: 15세 이상 20세 미만20~29: 20세 이상 30세 미만30~39: 30세 이상 40세 미만40~49: 40세 이상 50세 미만50~59: 50세 이상 60세 미만60~69: 60세 이상 70세 미만70~79: 70세 이상 80세 미만80~89: 80세 이상 90세 미만90~: 90세 이상필요한 동의항목: 연령대 | X |
| birthyear | String | 출생 연도(YYYY 형식) 필요한 동의항목: 출생 연도 | X |
| birthday | String | 생일(MMDD 형식) 필요한 동의항목: 생일 | X |
| birthday_type | String | 생일 타입, SOLAR(양력) 또는 LUNAR(음력)필요한 동의항목: 생일 | X |
| is_leap_month | Boolean | 생일의 윤달 여부 필요한 동의항목: 생일 | X |
| gender | String | 성별, female(여성) 또는 male(남성)필요한 동의항목: 성별 | X |
| is_kakaotalk_user | Boolean | 카카오톡 서비스 가입 여부 필요한 동의항목: 카카오톡 서비스 가입 여부 | X |
| phone_number | String | 카카오계정의 전화번호 국내 번호인 경우 +82 00-0000-0000 형식해외 번호인 경우 자릿수와 '-'의 유무나 위치가 다를 수 있음 (참고: libphonenumber) 필요한 동의항목: 카카오계정(전화번호) | X |
| ci | String | 연계정보 필요한 동의항목: CI(연계정보) | X |
| ci_authenticated_at | Datetime | 본인인증기관이 CI를 발급한 시각, UTC (RFC3339 internet date/time 형식) 필요한 동의항목: CI(연계정보) | X |
| account_id Permission Internal Only | Long | 카카오계정 ID | X |
| talk_user_id Permission Internal Only | Long | 카카오톡 회원번호 | X |
| legal_name | String | 본인인증을 거친 카카오계정 사용자 실명 필요한 동의항목: 본인확인정보(이름) | X |
| legal_birth_date | String | 본인인증을 거친 법정 생년월일(yyyyMMDD 형식) 필요한 동의항목: 본인확인정보(생년월일) | X |
| legal_gender | String | 본인인증을 거친 법정 성별female(여성) 또는 male(남성)필요한 동의항목: 본인확인정보(성별) | X |
| is_korean | Boolean | 본인인증을 거친 내국인 여부(대한민국 국적 보유 여부)true(내국인) 또는 false(외국인)필요한 동의항목: 본인확인정보(내/외국인) | X |
| account_creation_date | Datetime | 카카오계정 가입일자, UTC (RFC3339 internet date/time 형식) 필요한 동의항목: 카카오계정 가입일자 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| nickname | String | 닉네임 필요한 동의항목: 닉네임 또는 프로필 정보(닉네임/프로필 사진) | X |
| thumbnail_image_url | String | 프로필 미리보기 이미지 URL, 110px * 110px 또는 100px * 100px 필요한 동의항목: 프로필 사진 또는 프로필 정보(닉네임/프로필 사진) | X |
| profile_image_url | String | 프로필 이미지 URL, 640px * 640px 또는 480px * 480px 필요한 동의항목: 프로필 사진 또는 프로필 정보(닉네임/프로필 사진) | X |
| is_default_image | Boolean | 프로필 이미지 URL이 기본 프로필 이미지 URL인지 여부 사용자가 등록한 프로필 이미지가 없을 경우, 기본 프로필 이미지 제공
필요한 동의항목: 프로필 사진 또는 프로필 정보(닉네임/프로필 사진) | X |
요청: OTP 토큰 방식
- 외부 API로 OTP 토큰을 사용해 요청
curl -v -G GET "https://kapi.kakao.com/v2/user/me" \-H "Authorization: OTP ${OTP_TOKEN}"
요청: OTP 위임 방식
- 파라미터
- OTP 토큰(
target_otp_token)
- OTP 토큰(
curl -v -G GET "http://kapi.kakao.com/v2/internal/user/me" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_otp_token=${OTP_TOKEN}"
응답: OTP 토큰 방식, 1회성 제공 동의한 사용자
- 아래 예제는 참고를 위해 모든 항목을 포함하고 있으나, 실제 API 응답에서 아래 정보는 둘 중 한 가지만 제공 가능합니다.
- 이름, 본인확인정보(이름)
- 성별, 본인확인정보(성별)
- 생일 및 출생연도, 본인확인정보(생년월일)
- 위 정보는 필요한 동의항목의 동시 설정이 불가능함
{"kakao_account": {// 프로필 1회성 제공 동의항목 필요"profile": {"nickname": "홍길동","thumbnail_image_url": "http://yyy.kakao.com/.../img_110x110.jpg","profile_image_url": "http://yyy.kakao.com/dn/.../img_640x640.jpg"},// 이메일 1회성 제공 동의항목 필요"is_email_valid": true,"is_email_verified": true,"email": "hong@gmail.com",// 이름 1회성 제공 동의항목 필요"name": "홍길동",// 연령대 1회성 제공 동의항목 필요"age_range": "20~29",// 출생년도 1회성 제공 동의항목 필요"birthyear": "2002",// 생일 1회성 제공 동의항목 필요"birthday": "1130","birthday_type": "SOLAR","is_leap_month": false,// 성별 1회성 제공 동의항목 필요"gender": "female",// CI(연계정보) 1회성 제공 동의항목 필요"ci": "${CI}","ci_authenticated_at": "2019-03-11T11:25:22Z",// 카카오톡 서비스 가입 여부 1회성 제공 동의항목 필요"is_kakaotalk_user": true,// 전화번호 1회성 제공 동의항목 필요"phone_number": false,// 본인확인정보(이름) 1회성 제공 동의항목 필요"legal_name": "홍길동",// 본인확인정보(생년월일) 1회성 제공 동의항목 필요"legal_birth_date": "20021130",// 본인확인정보(성별) 1회성 제공 동의항목 필요"legal_gender": "female",// 본인확인정보(내/외국인) 1회성 제공 동의항목 필요"is_korean": true}}
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET | 카카오http://kapi.kakao.com/v1/internal/user/shipping_address공동체 https://kapi.kakao.com/v1/internal/user/shipping_address외부 https://kapi.kakao.com/v1/user/shipping_address | OTP OTP 위임 |
사용자 카카오계정의 배송지를 조회합니다. 이 기능을 사용하려면 권한 및 동의항목 설정이 필요합니다. 자세한 안내는 배송지를 참고합니다.
헤더에 OTP 토큰을 담아 GET으로 요청합니다. 성공 시 응답은 사용자의 배송지 목록을 포함합니다. address_id 파라미터로 특정 배송지 ID를 지정해 해당 배송지 정보를 받을 수 있습니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: OTP ${OTP_TOKEN}인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| address_id | Long | 배송지 정보가 많은 경우, 특정 배송지 정보만 얻고 싶을 때 배송지 ID 지정 | X |
| from_updated_at | Integer | 배송지 정보가 많아 여러 페이지에 걸쳐서 응답이 제공될 때 조회 기준이 되는 배송지 수정 시각 해당 시각 전에 수정된 배송지부터 조회하며, 이전 응답 페이지의 마지막 배송지의 updated_at을 다음 페이지 요청 시 사용(기본값: 0, 처음부터) | X |
| page_size | Integer | 한 페이지에 포함할 배송지 개수(기본값: 10, 최소 2) | X |
- 내부 API 요청 시에만 사용 가능합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
- OTP 위임 방식은 아래와 같은 경우에 사용합니다.
- OTP 토큰이 서비스로 제공하지 않고 카카오 내부 플랫폼에서 관리됨
- 카카오 내부 플랫폼이 서비스를 대신해 요청하고 서비스로 정보 전달
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_otp_token | String | API 호출 서비스 앱의 OTP 토큰 | O |
| address_id | Long | 배송지 정보가 많은 경우, 특정 배송지 정보만 얻고 싶을 때 배송지 ID 지정 | X |
| from_updated_at | Integer | 배송지 정보가 많아 여러 페이지에 걸쳐서 응답이 제공될 때 조회 기준이 되는 배송지 수정 시각 해당 시각 전에 수정된 배송지부터 조회하며, 이전 응답 페이지의 마지막 배송지의 updated_at을 다음 페이지 요청 시 사용(기본값: 0, 처음부터) | X |
| page_size | Integer | 한 페이지에 포함할 배송지 개수(기본값: 10, 최소 2) | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| shipping_addresses | ShippingAddress[] | 사용자의 배송지 정보 리스트 최신순 정렬 기본 배송지는 수정 시각과 관계 없이 첫 번째에 위치 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| id | Long | 배송지 ID | O |
| name | String | 배송지명 | X |
| is_default | Boolean | 기본 배송지 여부 | O |
| updated_at | Integer | 수정 시각(timestamp) | X |
| type | String | 배송지 타입, 구주소(OLD, 지번 및 번지 주소) 또는 신주소(NEW, 도로명 주소) | X |
| base_address | String | 우편번호 검색시 채워지는 기본 주소 | X |
| detail_address | String | 기본 주소에 추가하는 상세 주소 | X |
| receiver_name | String | 수령인 이름 | X |
| receiver_phone_number1 | String | 수령인 연락처 | X |
| receiver_phone_number2 | String | 수령인 추가 연락처 | X |
| zone_number | String | 신주소 우편번호, 신주소인 경우 반드시 존재 | X |
| zip_code | String | 구주소 우편번호 구주소는 우편번호를 소유하지 않는 경우가 있어, 구주소라도 해당 값이 없을 수 있음 | X |
요청: OTP 토큰 방식
- 파라미터
- 없음
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/shipping_address" \-H "Authorization: OTP ${OTP_TOKEN}"
요청: OTP 위임 방식
- 파라미터
- OTP 토큰(
target_otp_token)
- OTP 토큰(
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/shipping_address" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_otp_token=${OTP_TOKEN}"
응답: OTP 토큰 방식 또는 OTP 위임 방식
{"shipping_addresses": [{"default": true,"id": 12003,"name": "회사","is_default": true,"updated_at": 1631772156,"type": "NEW","base_address": "경기 성남시 분당구 판교역로 235","detail_address": "8층 카카오 택배보관소","receiver_name": "네오_Neo","receiver_phone_number1": "010-1234-5678","receiver_phone_number2": "","zone_number": "13494","zip_code": ""},{"default": false,"id": 12004,"name": "집","is_default": false,"updated_at": 1631772253,"type": "OLD","base_address": "경기 성남시 분당구 삼평동 681","detail_address": "7층 카카오","receiver_name": "네오","receiver_phone_number1": "010-1234-5678","receiver_phone_number2": "","zone_number": "13494","zip_code": ""}]}
| 메서드 | URL | 인증 방식 |
|---|---|---|
GET / POST | 카카오http://kapi.kakao.com/v2/internal/talk/channels공동체 https://kapi.kakao.com/v2/internal/talk/channels외부 https://kapi.kakao.com/v2/api/talk/channels | OTP OTP 위임 |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| 필요: 비즈 채널 앱 또는 공동체 앱 | 어드민 키 카카오 로그인 활성화 동의항목 카카오톡 채널 설정 | - | 필요: 카카오톡 채널 추가 상태 및 내역 |
사용자와 카카오톡 채널이 친구 관계인지 확인합니다. 이 API를 사용해 사용자와 카카오톡 채널이 친구가 아닐 때 친구 추가 버튼을 노출하거나, 이미 친구일 때 친구 요청을 하지 않도록 할 수 있습니다. 보다 자세한 설명은 카카오톡 채널 및 카카오톡 채널 관계 조회를 참고합니다.
헤더에 OTP 토큰을 담아 GET 또는 POST로 요청합니다. OTP 토큰으로 요청 시, OTP 토큰에 포함된 카카오톡 채널 프로필 ID에 해당하는 카카오톡 채널과 사용자의 관계를 확인합니다. OTP 토큰에 카카오톡 채널 정보가 없는 경우, 요청 대상 앱에 연결 또는 수동 등록된 카카오톡 채널에 대해 사용자와의 관계를 확인합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: OTP ${OTP_TOKEN}인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
- 내부 API 요청 시에만 사용 가능합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_otp_token | String | API 호출 서비스 앱의 OTP 토큰 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| channels | Channel[] | 각 카카오톡 채널과 사용자의 관계 정보 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| channel_talk_id | Long | 카카오톡 채널 ID 제공 조건: 인하우스 앱으로 요청한 경우, 또는 카카오톡 회원번호(talk_id) 응답 권한을 보유한 경우 | X |
| channel_public_id | String | 사용자의 친구로 추가된 카카오톡 채널의 프로필 ID | O |
| channel_uuid | String | 카카오톡 채널의 카카오톡 검색용 ID | O |
| relation | String | 사용자와 카카오톡 채널의 관계, 아래 중 하나
| O |
| created_at | Datetime | 카카오톡 채널 추가 시간, UTC* 카카오톡 채널이 추가( ADDED) 상태인 경우만 포함 | X |
| updated_time | datetime | 관계가 변경된 시각 친구 관계일 경우 친구 추가 시각(RFC3339 internet date/time 형식) | X |
요청: OTP 토큰 방식
curl -v -G GET "http://kapi.kakao.com/v2/internal/talk/channels" \-H "Authorization: OTP ${OTP_TOKEN}"
요청: OTP 위임 방식
curl -v -G GET "http://kapi.kakao.com/v2/internal/talk/channels" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_otp_token=${OTP_TOKEN}"
응답
{"channels": [{"channel_talk_id": 213228,"channel_public_id": "_NzL","channel_uuid": "@dev_sample","relation": "NONE"}]}
| 메서드 | URL | 인증 방식 |
|---|---|---|
POST | 카카오http://kapi.kakao.com/v2/internal/talk/channels/add공동체 https://kapi.kakao.com/v2/internal/talk/channels/add외부 https://kapi.kakao.com/v2/api/talk/channels/add | OTP OTP 위임 |
특정 카카오톡 채널을 사용자의 친구로 추가합니다. 사용자가 해당 카카오톡 채널을 차단한 상태일 경우, 차단을 해제하고 친구 추가합니다. 이 API 사용 시 주의 사항은 카카오톡 채널 친구 추가에서 확인할 수 있습니다.
헤더에 OTP 토큰을 담아 POST로 요청합니다. OTP 토큰으로 요청 시, OTP 토큰에 포함된 카카오톡 채널 프로필 ID에 해당하는 카카오톡 채널을 사용자의 친구로 추가합니다. OTP 토큰에 카카오톡 채널 정보가 없는 경우, 요청 대상 앱에 연결 또는 수동 등록된 카카오톡 채널을 사용자의 친구로 추가합니다. 요청 성공 시 응답은 사용자의 친구로 추가된 카카오톡 채널의 정보를 포함합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: OTP ${OTP_TOKEN}인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
- 내부 API 요청 시에만 사용 가능합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
- OTP 위임 방식은 아래와 같은 경우에 사용합니다.
- OTP 토큰이 서비스로 제공하지 않고 카카오 내부 플랫폼에서 관리됨
- 카카오 내부 플랫폼이 서비스를 대신해 요청하고 서비스로 정보 전달
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_otp_token | String | API 호출 서비스 앱의 OTP 토큰 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| channels | Channel[] | 친구로 추가한 카카오톡 채널 정보 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| channel_talk_id | Long | 카카오톡 채널 ID 제공 조건: 카카오톡 회원번호(talk_id) 응답 권한 보유, 내부 API 요청 | X |
| channel_public_id | String | 사용자의 친구로 추가된 카카오톡 채널 프로필 ID | O |
| channel_uuid | String | 카카오톡 채널의 카카오톡 검색용 ID | O |
| success | Boolean | 친구 추가 성공 여부
| O |
| failure_msg | String | 친구 추가 실패 원인을 담은 메시지 여러 개의 카카오톡 채널에 대한 친구 추가 요청 시에만 응답에 포함 INVALID_CHANNEL: 존재하지 않거나 삭제된 카카오톡 채널BLOCKED_CHANNEL: 제재 상태인 카카오톡 채널UNDER_AGE_LIMIT: 연령인증이 필요한 채널MAX_CHANNELS_LIMIT: 사용자가 추가할 수 있는 카카오톡 채널의 최대 수를 넘어선 경우ERROR: 카카오톡 채널 PAPI 내부 서버 오류참고: 하나의 채널 추가 요청이 실패한 경우에는 응답의 에러 코드로 원인 확인 | X |
요청: OTP 토큰 방식
curl -v -X POST "http://kapi.kakao.com/v2/internal/talk/channels/add" \-H "Authorization: OTP ${OTP_TOKEN}"
요청: OTP 위임 방식
curl -v -X POST "http://kapi.kakao.com/v2/internal/talk/channels/add" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_otp_token=${OTP_TOKEN}"
응답
{"channels": [{"channel_talk_id": 60896, // 카카오톡 회원번호 응답 권한 필요"channel_public_id": "_Bxkd","channel_uuid": "@릴리","success": true},{"channel_talk_id": 65282, // 카카오톡 회원번호 응답 권한 필요"channel_public_id": "_RQxl","channel_uuid": "@jwp_","success": true},{"channel_talk_id": 194285, // 카카오톡 회원번호 응답 권한 필요"channel_public_id": "_vxfxm","channel_uuid": "@5460866932883","success": false,"failure_msg": "BLOCKED_CHANNEL"}]}
| 메서드 | URL | 인증 방식 |
|---|---|---|
DELETE | 카카오http://kapi.kakao.com/v2/internal/calendar/delete/event공동체 https://kapi.kakao.com/v2/internal/calendar/delete/event | OTP OTP 위임 |
사용자의 일반 일정을 삭제합니다.
OTP 토큰을 헤더에 담아 파라미터와 함께 DELETE로 요청합니다. 일반 일정의 ID를 파라미터에 포함해야 합니다.
요청 성공 시 응답은 삭제한 일정의 ID를 포함한 JSON 객체입니다. 요청 실패 시 에러 코드에서 원인을 확인합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: OTP ${OTP_TOKEN}인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| event_id | String | 일정 ID | O |
| recur_update_type | String | 반복 일정의 수정 범위
주의: 반복 일정인 경우 필수 | X |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_otp_token | String | API 호출 서비스 앱의 OTP 토큰 | O |
| target_id | String | 사용자 ID | O |
| target_id_type | String | target_id 타입, 아래 중 하나
| O |
| event_id | String | 일정 ID | O |
| recur_update_type | String | 반복 일정의 수정 범위
주의: 반복 일정인 경우 필수 | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| event_id | String | 삭제한 일정 ID 주의: 반복 일정이 아닌 경우 필수 | X |
요청: OTP 토큰 방식
- 파라미터
- 일정 ID(
event_id)
- 일정 ID(
curl -v -G -X DELETE "http://kapi.kakao.com/v2/internal/calendar/delete/event" \-H "Authorization: OTP ${OTP_TOKEN}" \-d "event_id=6375dc4638e1f752188e12d4"
요청: OTP 위임 방식
- 파라미터
- OTP 토큰(
target_otp_token) - 사용자 ID(
target_id) - 사용자 ID 타입(
target_id_type): 회원번호(user_id) - 일정 ID(
event_id)
- OTP 토큰(
curl -v -G -X DELETE "http://kapi.kakao.com/v2/internal/calendar/delete/event" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_otp_token=${OTP_TOKEN}" \-d "target_id_type=user_id" \-d "target_id=1376016924430691663" \-d "event_id=6375dc4738e1f752188e12d8"
응답: OTP 토큰 방식 또는 OTP 위임 방식
// HTTP/1.1 200 OK{"event_id": "6351f57c7ec8e318d0b809a0"}
| 메서드 | URL | 인증 방식 |
|---|---|---|
POST | 카카오http://kapi.kakao.com/v2/internal/calendar/public/follow공동체 https://kapi.kakao.com/v2/internal/calendar/public/follow | OTP OTP 위임 |
| 권한 | 사전 설정 | 카카오 로그인 | 동의항목 |
|---|---|---|---|
| 필요: 사용 권한 | 어드민 키 카카오 로그인 활성화 동의항목 카카오톡 채널 연결 | 필요: 연결 | 필요: 이용 정책 참고 |
공개 일정을 사용자의 톡캘린더에 추가합니다. 앱과 연결된 카카오톡의 공개 일정만 사용자 캘린더에 추가할 수 있습니다. 공개 일정이 변경 또는 삭제될 경우, 사용자 캘린더에 추가된 공개 일정도 변경 또는 삭제될 수 있습니다.
OTP 토큰을 헤더에 담아 POST로 요청합니다. 파라미터로 공개 일정을 추가할 사용자 캘린더 ID, 공개 일정 ID를 전달해야 합니다.
요청 성공 시 응답은 사용자 캘린더에 추가된 공개 일정 ID를 포함합니다. 요청 실패 시 에러 코드에서 원인을 확인합니다.
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: OTP ${OTP_TOKEN}인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| event_id | String | 공개 일정 ID | O |
| calendar_id | String | 사용자 캘린더 ID(기본값: primary) | X |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
| Content-Type | Content-Type: application/x-www-form-urlencoded;charset=utf-8요청 데이터 타입 | O |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_otp_token | String | API 호출 서비스 앱의 OTP 토큰 | O |
| target_id | String | 사용자 ID | O |
| target_id_type | String | target_id 타입, 아래 중 하나
| O |
| event_id | String | 공개 일정 ID | O |
| calendar_id | String | 사용자 캘린더 ID(기본값: primary) | X |
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| event_id | String | 공개 일정 ID | O |
요청: OTP 토큰 방식
- 파라미터
- 카카오톡 채널 프로필 ID(
channel_public_id) - 일정 ID(
event_id) - 사용자 캘린더 ID(
calendar_id)
- 카카오톡 채널 프로필 ID(
curl -v -X POST "http://kapi.kakao.com/v2/internal/calendar/public/follow" \-H "Authorization: OTP ${OTP_TOKEN}" \-d "event_id=637608a438e1f752188e137b" \-d "calendar_id=user_6375c8e638e1f752188e114e"
요청: OTP 위임 방식
- 파라미터
- OTP 토큰(
target_otp_token) - 카카오톡 채널 프로필 ID(
channel_public_id) - 일정 ID(
event_id) - 사용자 캘린더 ID(
calendar_id)
- OTP 토큰(
curl -v -X POST "http://kapi.kakao.com/v2/internal/calendar/public/follow" \-H "Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}" \-d "target_otp_token=${OTP_TOKEN}" \-d "target_id_type=user_id" \-d "target_id=1376016924430691663" \-d "event_id=637608a438e1f752188e137b" \-d "calendar_id=user_6375c8e638e1f752188e114e"
응답: OTP 토큰 방식 또는 OTP 위임 방식
// HTTP/1.1 200 OK{"event_id": "637608a438e1f752188e137b"}
| 메서드 | URL | 인증 방식 |
|---|---|---|
POST | 카카오http://kapi.kakao.com/v1/internal/app/checkquota공동체 https://kapi.kakao.com/v1/internal/app/checkquota | OTP OTP 위임 |
패시브 연동 API는 API 제공 시 카카오 API 플랫폼과 KAPI 패시브 연동 방식으로 연동하기 위해 호출해야 하는 API입니다. 이 API는 API 호출 서비스 앱과 사용자 인증, 권한 및 쿼터 확인, 통계를 위한 데이터 수집을 처리합니다. 보다 자세한 정보는 KAPI 패시브 연동을 참고합니다.
1회성 제공 동의 사용 시, 아래와 같은 용도로 패시브 연동 API를 사용합니다.
- OTP 토큰 유효성 검증
- 패시브 연동 API를 요청한 앱이 Quota URI에 해당하는 API의 사용 권한이 있는지 확인
- Quota URI에 해당하는 API에 설정된 동의항목의 1회성 동의 여부 확인
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: OTP ${OTP_TOKEN}인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
- 아래 중 하나의 파라미터는 필수 전달해야 합니다.
target_otp_tokentarget_app_key와target_otp_account_id
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_app_key | String | API 호출 서비스 앱의 키 | O(Optional) |
| target_otp_token | String | API 호출 서비스 앱의 OTP 토큰 | O(Optional) |
| target_otp_account_id | String | 사용자 카카오계정 ID 사용자 카카오계정의 상태를 검증하고, 필요 시 사용자 제재가 가능하도록 하기 위해 전달 중요: target_otp_account_id로 요청 시, 해당 사용자의 동의 여부 확인은 불가능하며 카카오계정의 상태 확인만 가능 | O(Optional) |
| target_kakao_agent | String | API 호출 서비스 앱의 추가 정보, ip 필수 전달중요: API 제공자 서버에서 REST API로 패시브 연동 API를 호출할 경우, target_app_key와 무관하게 ip를 포함해야 함참고: KA 헤더 정보 | O |
| quota_properties | JSON | API의 쿼터 제한 시 사용한 팩터(Factor)uri 키(Key)와 quota_uri 값(Value)으로 구성API플랫폼에 등록한 값만 사용 가능 ( {"key":"value"} 형식)(예: {"uri":"/v1/api/talk/profile"})중요: API 호출 서비스와 사용자가 연결된 경우의 호출과 구분할 수 있도록 quota_properties의 Quota URI를 다르게 지정해 사용할 것 | O |
| extra_properties | JSON | API 제공자별로 필요한 추가 정보, {"key":"value"} 형식추가 검증이나 로그 분석에 필요 | X |
| property_keys | String[] | target_id로 사용자 인증을 요청하는 경우에만 사용 가능응답에 추가로 포함할 사용자 ID를 지정하는 데 사용, 아래 중 하나
'property_keys=["user_id","account_id"]') | X |
| operation | String | 쿼터에 대해 수행할 동작, 아래 중 하나
increase)참고: 각 동작의 용도는 아래와 같습니다. increase, descrease: API 요청에 따라 해당 사용자의 쿼터 소모량을 1 증가 또는 감소시킬 때 사용
| X |
| operand | Integer | operation 값을 add로 지정한 경우, 증가 또는 감소시킬 쿼터량operation 값을 check로 지정한 경우, 남은 쿼터에 operand의 수치만큼 쿼터 소모량이 증가했을 때 쿼터 초과 여부를 확인 가능(기본값: 1) | X |
| 이름 | 설명 | 필수 |
|---|---|---|
| Authorization | Authorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}인증 방식, 플랫폼 앱 어드민 키로 인증 요청 서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능 필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요 1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능 | O |
- 아래 중 하나의 파라미터는 필수 전달해야 합니다.
target_otp_tokentarget_app_key와target_otp_account_id
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| target_app_key | String | API 호출 서비스 앱의 키 | O(Optional) |
| target_otp_token | String | API 호출 서비스 앱의 OTP 토큰 | O(Optional) |
| target_otp_account_id | String | 사용자 카카오계정 ID 사용자 카카오계정의 상태를 검증하고, 필요 시 사용자 제재가 가능하도록 하기 위해 전달 중요: target_otp_account_id로 요청 시, 해당 사용자의 동의 여부 확인은 불가능하며 카카오계정의 상태 확인만 가능 | O(Optional) |
| target_kakao_agent | String | API 호출 서비스 앱의 추가 정보, ip 필수 전달중요: API 제공자 서버에서 REST API로 패시브 연동 API를 호출할 경우, target_app_key와 무관하게 ip를 포함해야 함참고: KA 헤더 정보 | O |
| quota_properties | JSON | API의 쿼터 제한 시 사용한 팩터(Factor)uri 키(Key)와 quota_uri 값(Value)으로 구성API플랫폼에 등록한 값만 사용 가능 ( {"key":"value"} 형식)(예: {"uri":"/v1/api/talk/profile"})중요: API 호출 서비스와 사용자가 연결된 경우의 호출과 구분할 수 있도록 quota_properties의 Quota URI를 다르게 지정해 사용할 것 | O |
| extra_properties | JSON | API 제공자별로 필요한 추가 정보, {"key":"value"} 형식추가 검증이나 로그 분석에 필요 | X |
| property_keys | String[] | target_id로 사용자 인증을 요청하는 경우에만 사용 가능응답에 추가로 포함할 사용자 ID를 지정하는 데 사용, 아래 중 하나
'property_keys=["user_id","account_id"]') | X |
| operation | String | 쿼터에 대해 수행할 동작, 아래 중 하나
increase)참고: 각 동작의 용도는 아래와 같습니다. increase, descrease: API 요청에 따라 해당 사용자의 쿼터 소모량을 1 증가 또는 감소시킬 때 사용
| X |
| operand | Integer | operation 값을 add로 지정한 경우, 증가 또는 감소시킬 쿼터량operation 값을 check로 지정한 경우, 남은 쿼터에 operand의 수치만큼 쿼터 소모량이 증가했을 때 쿼터 초과 여부를 확인 가능(기본값: 1) | X |
요청: OTP 토큰을 사용한 사용자 인증 요청
curl -v -X POST "http://kapi.kakao.com/v1/internal/app/checkquota" \-H "Authorization: KakaoAK ${API_PROVIDER_APP_ADMIN_KEY}" \-d 'target_otp_token=${OTP_TOKEN}' \--data-urlencode 'target_kakao_agent=ip/${API_CALLER_IP}' \--data-urlencode 'quota_properties={"uri":"${URI}"}'