본문 바로가기메인 메뉴 바로가기사이드 메뉴 바로가기

kakao developers

관련사이트

사이드 메뉴

플랫폼 API

API 제공

전용 API

어드민 API

이 문서는 1회성 제공 동의 사용 방법을 안내합니다.

1회성 제공 동의는 사용자에게 1회성으로 특정 개인정보 제공 동의를 받아 카카오 API를 호출하기 위해 사용하는 단발성 인증 방법입니다. 1회성 제공 동의로 발급하는 OTP 토큰으로 일부 API를 호출할 수 있습니다.

아래는 1회성 제공 동의로 API를 호출하는 과정을 표현한 이미지입니다.

1회성 제공 동의를 사용한 API 호출 과정

  1. OTP: 인가 코드 요청으로 사용자에게 1회성 제공 동의를 요청하고 인가 코드를 발급받습니다.
  2. 1의 결과로 발급받은 인가 코드로 OTP: 토큰 요청을 호출해 OTP 토큰을 발급받습니다.
  3. 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시간
* 개별 앱의 OTP 토큰 만료 시간은 사용 목적에 따라 플러그인 타입별 토큰 최대 만료 시간 이내로 각각 설정 가능

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. 요구 사항 검토
  2. 신청

위 과정에는 카카오디벨로퍼스 앱이 반드시 필요합니다. 아직 앱이 없다면, 앱 설정 > 앱인하우스 앱을 참고해 새로운 앱을 등록해야 합니다.

서비스에서 1회성 제공 동의를 사용해 구현하려는 기능이 무엇인지에 따라, 필요한 사용자 정보나 동작을 제공하는 API가 무엇인지 확인합니다.

  • 1회성 제공 동의 타입에 따라 제공 가능한 사용자 정보의 종류가 제한될 수 있습니다. 자세한 내용은 1회성 제공 동의 타입 표의 동의항목을 참고합니다.
  • 일부 사용자 정보는 권한이 있어야 제공받을 수 있습니다. 해당 정보를 제공하는 API의 개발 문서를 참고합니다.
사용자 정보동의항목API
카카오계정 ID-사용자 정보 조회
카카오톡 회원번호-사용자 정보 조회
프로필 정보(닉네임/프로필 사진)닉네임
프로필 사진
프로필 정보(닉네임/프로필 사진)
사용자 정보 조회
이메일카카오계정(이메일)사용자 정보 조회
유효 이메일 여부카카오계정(이메일)사용자 정보 조회
이메일 인증 여부카카오계정(이메일)사용자 정보 조회
이름이름사용자 정보 조회
성별성별사용자 정보 조회
연령대연령대사용자 정보 조회
출생연도출생연도사용자 정보 조회
생일생일사용자 정보 조회
전화번호카카오계정(휴대전화번호)사용자 정보 조회
카카오계정 가입일자카카오계정 가입일자사용자 정보 조회
CI(연계정보)CI(연계정보)사용자 정보 조회
본인인증 받은 시각CI(연계정보)사용자 정보 조회
본인확인정보(이름)본인확인정보(이름)사용자 정보 조회
본인확인정보(생년월일)본인확인정보(생년월일)사용자 정보 조회
본인확인정보(성별)본인확인정보(성별)사용자 정보 조회
본인확인정보(내외국인)본인확인정보(내외국인)사용자 정보 조회
카카오톡 서비스 가입 여부카카오톡 서비스 가입 여부사용자 정보 조회
배송지정보(수령인명, 배송지 주소, 전화번호)배송지정보(수령인명, 배송지 주소, 전화번호)배송지 조회
카카오톡 채널 추가 상태 및 내역카카오톡 채널 추가 상태 및 내역카카오톡 채널 관계 조회
  • 공동체의 경우, 아래 중 일부 API를 사용하려면 권한이 필요합니다. 권한을 참고합니다.
Permission
: 권한 필요
API필요한 동의항목설명
사용자 정보 조회1회성 제공 동의를 지원하는 사용자 정보 참고사용자가 1회성 제공 동의한 항목의 정보를 조회합니다.
배송지 조회
Permission
배송지정보(수령인명, 배송지 주소, 전화번호)사용자 카카오계정의 배송지 정보를 조회합니다.
카카오톡 채널 친구 추가
Permission
카카오톡 채널 추가 상태 및 내역특정 카카오톡 채널을 사용자의 친구로 추가합니다.
톡캘린더 일반 일정 삭제
Permission
톡캘린더 및 일정 생성, 조회, 편집/삭제사용자의 일반 일정을 삭제합니다.
톡캘린더 공개 일정 사용자 캘린더에 추가
Permission
톡캘린더 및 일정 생성, 조회, 편집/삭제공개 일정을 사용자의 톡캘린더에 추가합니다.
패시브 연동
Permission
-OTP 토큰 인증이 필요한 경우에 사용합니다.

[서비스] API플랫폼 아지트로 아래 정보를 전달합니다.

항목설명
앱 이름과 ID앱 관리 페이지의 [대시보드]에서 확인 가능
DEFAULT_INHOUSE 타입을 사용하려는 경우, 요청을 위임받은 플랫폼 앱의 정보도 함께 전달
필요한 동의항목과 API1회성 제공 동의 시 사용하려는 동의항목과 API
1. 요구 사항 검토 참고
사용 목적필요한 동의항목과 API의 사용 시나리오 등 필요한 기능에 대한 설명
제공 목적 안내 문구1회성 제공 동의의 동의 화면에 노출할 개인정보 수집 목적 안내
(예: "${SERVICE_NAME} 서비스의 ${EVENT_NAME} 이벤트를 위해")
제공 기간 안내 문구1회성 제공 동의의 동의 화면에 노출할 개인정보 처리 안내
(예: "제공목적 달성 후 지체없이 파기")
개인정보 처리방침 및 검토 의견1회성 제공 동의로 제공받은 개인정보 처리방침
1회성 제공 동의를 사용하려는 기능에 대한 개인정보 검토 의견
메서드URL인증 방식
GET외부
https://kauth.kakao.com/oauth/authorize
-

사용자에게 1회성 제공 동의를 요청하는 동의 화면을 출력하고, OTP 토큰을 발급받기 위한 인가 코드를 발급받습니다. 요청 과정은 일반적인 카카오 로그인의 인가 코드 요청과 거의 동일하나, 1회성 제공 동의 요청에 필요한 파라미터를 추가 전달해야 하는 점에 주의합니다.

이름타입설명필수
client_idString서비스 앱 REST API 키
앱 관리 페이지의 [앱] > [플랫폼 키] > REST API 키에서 확인 가능
O
redirect_uriString인가 코드를 전달받을 리다이렉트 URI
앱 관리 페이지의 [앱] > [플랫폼 키] > [REST API 키] > [리다이렉트 URI]에서 확인 가능

중요:
DEFAULT_INHOUSE 타입의 경우, 요청을 위임받은 플랫폼 앱에 redirect_uri 값이 등록되어 있어야 함
O
response_typeStringcode로 고정O
pluginString앱에 설정된 1회성 제공 동의 타입, 아래 중 하나
  • default: DEFAULT 타입
  • default_inhouse: DEFAULT_INHOUSE 타입
  • survey: SURVEY 타입
  • ket_event: KET_EVENT 타입
O
plugin_ext_idInteger타입별 확장 키
SURVEY 타입 전용 필수 파라미터
요청 시 상황에 따라 타입의 기본 설정이 아닌 별도 설정을 적용하고자 할 때 사용
plugin_ext_id 파라미터 미사용 시, 동의항목 설정과 토큰 만료 시간은 타입별 기본 설정을 따름
X*
delegate_client_idStringDEFAULT_INHOUSE 타입 전용 필수 파라미터
요청을 위임받은 플랫폼 앱의 REST API 키
X*
ket_event_cpidStringKET_EVENT 타입 전용 필수 파라미터
사용자와의 관계를 확인할 카카오톡 채널의 프로필 ID
카카오톡 채널 추가 상태 및 내역 동의항목의 1회성 제공 동의로 해당 카카오톡 채널에 대한 카카오톡 채널 관계 조회 API 요청 가능

참고: 카카오톡 채널 프로필 ID 확인 방법
X*
stateString로그인 요청과 웹훅 간에 상태를 유지하기 위해 사용되는 임의의 문자열(정해진 형식 없음)
Cross-Site Request Forgery(CSRF) 공격으로부터 보호하기 위해 해당 파라미터 사용을 권장함
X
* 특정 타입의 경우 필수 파라미터, Description 참고

인가 코드 요청의 응답은 HTTP 302 리다이렉트되어, redirect_uriGET 요청으로 전달됩니다. 아래 쿼리 파라미터를 포함합니다.

이름타입설명필수
codeStringOTP: 토큰 발급에 사용할 인가 코드O
https://kauth.kakao.com/oauth/authorize?client_id=${SERVICE_APP_REST_API_KEY}&redirect_uri=${REDIRECT_URI}&response_type=code&plugin=default&state=test
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
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 302
Location: ${REDIRECT_URI}?code=${AUTHORIZATION_CODE}
메서드URL인증 방식
POST외부
https://kauth.kakao.com/oauth/token
-

인가 코드를 전달하고 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 키의 클라이언트 시크릿 기본 활성화

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

이름타입설명필수
grant_typeStringauthorization_code로 고정O
client_idString서비스 앱 REST API 키
앱 관리 페이지의 [앱] > [플랫폼 키] > REST API 키에서 확인 가능
O
redirect_uriString인가 코드가 전달된 리다이렉트 URI
앱 관리 페이지의 [앱] > [플랫폼 키] > [REST API 키] > [리다이렉트 URI]에서 확인 가능

중요:
DEFAULT_INHOUSE 타입의 경우, 요청을 위임받은 플랫폼 앱에 redirect_uri 값이 등록되어 있어야 함
O
codeString인가 코드 요청으로 얻은 인가 코드O
delegate_client_idStringDEFAULT_INHOUSE 타입 전용 필수 파라미터
요청을 위임받은 플랫폼 앱의 REST API 키
X*
client_secretString토큰 발급 시, 보안을 강화하기 위해 추가 확인하는 클라이언트 시크릿 코드
앱 관리 페이지의 [앱] > [플랫폼 키] > [REST API 키]에서 설정 가능
[ON] 상태인 경우 필수로 요청에 포함해야 함
X
* 특정 타입의 경우 필수 파라미터, Description 참고
이름타입설명필수
access_tokenString1회성 제공 동의로 발급받은 OTP 토큰 값, JWT 규격을 따름
BASE64 URL-Safe 인코딩 값으로, 디코딩해 토큰 상세 정보 확인 가능
아래 JWT Header, JWT Payload 표 참고
O
token_typeStringotp로 고정O
expires_inInteger토큰 만료 시간(초)O
scopeString사용자가 1회성 제공 동의한 동의항목
여러 개일 경우, 공백으로 구분
사용자가 동의한 동의항목이 없을 경우, 응답에 scope 필드 미포함
X
이름타입설명필수
typString토큰 타입 정보
JWT로 고정
O
algString토큰 암호화 알고리즘 정보
HS256로 고정
O
이름타입설명필수
audString앱 IDO
subString암호화된 사용자 IDO
scopeString[]사용자가 1회성 제공 동의한 동의항목 목록
사용자가 동의한 동의항목이 없을 경우 빈 배열로 JWT Payload에 포함됨
O
issInteger토큰 발행처, https://kauth.kakao.com으로 고정O
expInteger토큰 만료 시간O
iatInteger토큰 발급 시간O
pidInteger앱의 1회성 제공 동의 설정 IDX
termsString[]SURVEY 타입에 대한 요청의 응답에만 포함
사용자가 동의한 서비스 약관 목록
X
cpidStringKET_EVENT 타입에 대한 요청의 응답에만 포함
OTP: 인가 코드 발급ket_event_cpid 파라미터로 전달한 카카오톡 채널 프로필 ID
X
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}"
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"
}
// 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 토큰의 유효성을 검증하는 용도로 사용합니다. 자세한 안내는 토큰 정보 조회를 참고합니다.

이름설명필수
AuthorizationAuthorization: OTP ${OTP_TOKEN}
인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
  • 내부 API 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
이름타입설명필수
target_otp_tokenStringAPI 호출 서비스 앱의 OTP 토큰O
이름타입설명필수
expires_inLong액세스 토큰의 만료 시간(단위: 초)O
app_idInt토큰이 발급된 앱 IDO
account_idInt카카오계정 ID

제공 조건: 카카오계정 ID 응답 권한 보유, 내부 API 요청
X
scopesString[]사용자가 동의한 동의항목 ID 목록O
* expiresInMillis, appId, kaccount_id: Deprecated, 각각 expires_in, app_id, account_id로 변경
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/access_token_info" \
-H "Authorization: OTP ${OTP_TOKEN}"
  • 외부 API 요청
curl -v -G GET "https://kapi.kakao.com/v1/user/access_token_info" \
-H "Authorization: OTP ${OTP_TOKEN}"
  • 파라미터
    • OTP 토큰(target_otp_token)
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}"
{
"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에 해당하는 사용자 정보를 포함합니다. 자세한 안내는 사용자 정보 조회를 참고합니다.

이름설명필수
AuthorizationAuthorization: OTP ${OTP_TOKEN}
인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
이름타입설명필수
secure_resourceBoolean이미지 URL 값의 HTTPS 반환 여부 (기본값: false)X
property_keysString[]응답에 포함할 정보의 키, 미지정 시 모든 정보 포함
키와 값의 쌍으로 구성
(예: ["id","properties.${CUSTOM_PROPERTY_KEY}",
"kakao_account.email"])
X
  • 내부 API 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
  • OTP 위임 방식은 아래와 같은 경우에 사용합니다.
    • OTP 토큰이 서비스로 제공하지 않고 카카오 내부 플랫폼에서 관리됨
    • 카카오 내부 플랫폼이 서비스를 대신해 요청하고 서비스로 정보 전달
이름타입설명필수
target_otp_tokenStringAPI 호출 서비스 앱의 OTP 토큰O
secure_resourceBoolean이미지 URL 값의 HTTPS 반환 여부 (기본값: false)X
property_keysString[]응답에 포함할 정보의 키, 미지정 시 모든 정보 포함
키와 값의 쌍으로 구성
(예: ["id","properties.${CUSTOM_PROPERTY_KEY}",
"kakao_account.email"])
X
  • 요청 시 property_keys 파라미터로 조회할 정보를 지정한 경우, 응답은 해당 값만 제공
이름타입설명필수
kakao_accountKakaoAccount카카오계정 정보X
Permission
: 권한 필요, 사용자 정보 참고
Internal Only
: 내부 API 요청 시에만 제공
has_${FIELD_NAME}: Deprecated, 각 사용자 정보 값 소유 여부(Boolean), 해당 사용자 정보의 제공 가능 여부를 확인하는 용도로 사용할 수 없음(참고: needs_agreement)
이름타입설명필수
profileJSON프로필 정보

필요한 동의항목: 닉네임, 프로필 사진, 프로필 정보(닉네임/프로필 사진)
X
is_email_validBoolean이메일 유효 여부
유효한 이메일이라면 true(유효), 이메일이 다른 카카오계정에 사용돼 만료되었다면 false(무효)

필요한 동의항목: 카카오계정(이메일)
X
is_email_verifiedBoolean이메일 인증 여부, true(인증된 이메일) 또는 false(인증되지 않은 이메일)

필요한 동의항목: 카카오계정(이메일)
X
emailString카카오계정 대표 이메일

필요한 동의항목: 카카오계정(이메일)
중요: 이메일 사용 시 주의 사항
X
nameString카카오계정의 이름
본인인증된 실명이 있다면 해당 값 제공
실명과 일치하지 않을 수 있으니, 실명이 필요할 경우 본인확인정보(이름) 사용 권장

필요한 동의항목: 이름
X
age_rangeString연령대
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
birthyearString출생 연도(YYYY 형식)

필요한 동의항목: 출생 연도
X
birthdayString생일(MMDD 형식)

필요한 동의항목: 생일
X
birthday_typeString생일 타입, SOLAR(양력) 또는 LUNAR(음력)

필요한 동의항목: 생일
X
is_leap_monthBoolean생일의 윤달 여부

필요한 동의항목: 생일
X
genderString성별, female(여성) 또는 male(남성)

필요한 동의항목: 성별
X
is_kakaotalk_userBoolean카카오톡 서비스 가입 여부

필요한 동의항목: 카카오톡 서비스 가입 여부
X
phone_numberString카카오계정의 전화번호
국내 번호인 경우 +82 00-0000-0000 형식
해외 번호인 경우 자릿수와 '-'의 유무나 위치가 다를 수 있음
(참고: libphonenumber)

필요한 동의항목: 카카오계정(전화번호)
X
ciString연계정보

필요한 동의항목: CI(연계정보)
X
ci_authenticated_atDatetime본인인증기관이 CI를 발급한 시각, UTC
(RFC3339 internet date/time 형식)

필요한 동의항목: CI(연계정보)
X
account_id
Permission
Internal Only
Long카카오계정 IDX
talk_user_id
Permission
Internal Only
Long카카오톡 회원번호X
legal_nameString본인인증을 거친 카카오계정 사용자 실명

필요한 동의항목: 본인확인정보(이름)
X
legal_birth_dateString본인인증을 거친 법정 생년월일(yyyyMMDD 형식)

필요한 동의항목: 본인확인정보(생년월일)
X
legal_genderString본인인증을 거친 법정 성별
female(여성) 또는 male(남성)
필요한 동의항목: 본인확인정보(성별)
X
is_koreanBoolean본인인증을 거친 내국인 여부(대한민국 국적 보유 여부)
true(내국인) 또는 false(외국인)

필요한 동의항목: 본인확인정보(내/외국인)
X
account_creation_dateDatetime카카오계정 가입일자, UTC
(RFC3339 internet date/time 형식)

필요한 동의항목: 카카오계정 가입일자
X
이름타입설명필수
nicknameString닉네임

필요한 동의항목: 닉네임 또는 프로필 정보(닉네임/프로필 사진)
X
thumbnail_image_urlString프로필 미리보기 이미지 URL, 110px * 110px 또는 100px * 100px

필요한 동의항목: 프로필 사진 또는 프로필 정보(닉네임/프로필 사진)
X
profile_image_urlString프로필 이미지 URL, 640px * 640px 또는 480px * 480px

필요한 동의항목: 프로필 사진 또는 프로필 정보(닉네임/프로필 사진)
X
is_default_imageBoolean프로필 이미지 URL이 기본 프로필 이미지 URL인지 여부
사용자가 등록한 프로필 이미지가 없을 경우, 기본 프로필 이미지 제공
  • true: 기본 프로필 이미지
  • false: 사용자가 등록한 프로필 이미지

필요한 동의항목: 프로필 사진 또는 프로필 정보(닉네임/프로필 사진)
X
  • 외부 API로 OTP 토큰을 사용해 요청
curl -v -G GET "https://kapi.kakao.com/v2/user/me" \
-H "Authorization: OTP ${OTP_TOKEN}"
  • 파라미터
    • OTP 토큰(target_otp_token)
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}"
  • 아래 예제는 참고를 위해 모든 항목을 포함하고 있으나, 실제 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를 지정해 해당 배송지 정보를 받을 수 있습니다.

이름설명필수
AuthorizationAuthorization: OTP ${OTP_TOKEN}
인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
이름타입설명필수
address_idLong배송지 정보가 많은 경우, 특정 배송지 정보만 얻고 싶을 때 배송지 ID 지정X
from_updated_atInteger배송지 정보가 많아 여러 페이지에 걸쳐서 응답이 제공될 때 조회 기준이 되는 배송지 수정 시각
해당 시각 전에 수정된 배송지부터 조회하며, 이전 응답 페이지의 마지막 배송지의 updated_at을 다음 페이지 요청 시 사용(기본값: 0, 처음부터)
X
page_sizeInteger한 페이지에 포함할 배송지 개수(기본값: 10, 최소 2)X
  • 내부 API 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
  • OTP 위임 방식은 아래와 같은 경우에 사용합니다.
    • OTP 토큰이 서비스로 제공하지 않고 카카오 내부 플랫폼에서 관리됨
    • 카카오 내부 플랫폼이 서비스를 대신해 요청하고 서비스로 정보 전달
이름타입설명필수
target_otp_tokenStringAPI 호출 서비스 앱의 OTP 토큰O
address_idLong배송지 정보가 많은 경우, 특정 배송지 정보만 얻고 싶을 때 배송지 ID 지정X
from_updated_atInteger배송지 정보가 많아 여러 페이지에 걸쳐서 응답이 제공될 때 조회 기준이 되는 배송지 수정 시각
해당 시각 전에 수정된 배송지부터 조회하며, 이전 응답 페이지의 마지막 배송지의 updated_at을 다음 페이지 요청 시 사용(기본값: 0, 처음부터)
X
page_sizeInteger한 페이지에 포함할 배송지 개수(기본값: 10, 최소 2)X
이름타입설명필수
shipping_addressesShippingAddress[]사용자의 배송지 정보 리스트
최신순 정렬
기본 배송지는 수정 시각과 관계 없이 첫 번째에 위치
X
이름타입설명필수
idLong배송지 IDO
nameString배송지명X
is_defaultBoolean기본 배송지 여부O
updated_atInteger수정 시각(timestamp)X
typeString배송지 타입, 구주소(OLD, 지번 및 번지 주소) 또는 신주소(NEW, 도로명 주소)X
base_addressString우편번호 검색시 채워지는 기본 주소X
detail_addressString기본 주소에 추가하는 상세 주소X
receiver_nameString수령인 이름X
receiver_phone_number1String수령인 연락처X
receiver_phone_number2String수령인 추가 연락처X
zone_numberString신주소 우편번호, 신주소인 경우 반드시 존재X
zip_codeString구주소 우편번호
구주소는 우편번호를 소유하지 않는 경우가 있어, 구주소라도 해당 값이 없을 수 있음
X
  • 파라미터
    • 없음
curl -v -G GET "http://kapi.kakao.com/v1/internal/user/shipping_address" \
-H "Authorization: OTP ${OTP_TOKEN}"
  • 파라미터
    • OTP 토큰(target_otp_token)
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}"
{
"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 토큰에 카카오톡 채널 정보가 없는 경우, 요청 대상 앱에 연결 또는 수동 등록된 카카오톡 채널에 대해 사용자와의 관계를 확인합니다.

이름설명필수
AuthorizationAuthorization: OTP ${OTP_TOKEN}
인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
  • 내부 API 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
이름타입설명필수
target_otp_tokenStringAPI 호출 서비스 앱의 OTP 토큰O
이름타입설명필수
channelsChannel[]각 카카오톡 채널과 사용자의 관계 정보X
이름타입설명필수
channel_talk_idLong카카오톡 채널 ID

제공 조건: 인하우스 앱으로 요청한 경우, 또는 카카오톡 회원번호(talk_id) 응답 권한을 보유한 경우
X
channel_public_idString사용자의 친구로 추가된 카카오톡 채널의 프로필 IDO
channel_uuidString카카오톡 채널의 카카오톡 검색용 IDO
relationString사용자와 카카오톡 채널의 관계, 아래 중 하나
  • ADDED: 친구
  • BLOCKED: 차단
  • NONE: 관계 없음
O
created_atDatetime카카오톡 채널 추가 시간, UTC*
카카오톡 채널이 추가(ADDED) 상태인 경우만 포함
X
updated_timedatetime관계가 변경된 시각
친구 관계일 경우 친구 추가 시각(RFC3339 internet date/time 형식)
X
curl -v -G GET "http://kapi.kakao.com/v2/internal/talk/channels" \
-H "Authorization: OTP ${OTP_TOKEN}"
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 토큰에 카카오톡 채널 정보가 없는 경우, 요청 대상 앱에 연결 또는 수동 등록된 카카오톡 채널을 사용자의 친구로 추가합니다. 요청 성공 시 응답은 사용자의 친구로 추가된 카카오톡 채널의 정보를 포함합니다.

이름설명필수
AuthorizationAuthorization: OTP ${OTP_TOKEN}
인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
  • 내부 API 요청 시에만 사용 가능합니다.
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
  • OTP 위임 방식은 아래와 같은 경우에 사용합니다.
    • OTP 토큰이 서비스로 제공하지 않고 카카오 내부 플랫폼에서 관리됨
    • 카카오 내부 플랫폼이 서비스를 대신해 요청하고 서비스로 정보 전달
이름타입설명필수
target_otp_tokenStringAPI 호출 서비스 앱의 OTP 토큰O
이름타입설명필수
channelsChannel[]친구로 추가한 카카오톡 채널 정보O
이름타입설명필수
channel_talk_idLong카카오톡 채널 ID

제공 조건: 카카오톡 회원번호(talk_id) 응답 권한 보유, 내부 API 요청
X
channel_public_idString사용자의 친구로 추가된 카카오톡 채널 프로필 IDO
channel_uuidString카카오톡 채널의 카카오톡 검색용 IDO
successBoolean친구 추가 성공 여부
  • true: 성공
  • false: 실패
O
failure_msgString친구 추가 실패 원인을 담은 메시지
여러 개의 카카오톡 채널에 대한 친구 추가 요청 시에만 응답에 포함
INVALID_CHANNEL: 존재하지 않거나 삭제된 카카오톡 채널
BLOCKED_CHANNEL: 제재 상태인 카카오톡 채널
UNDER_AGE_LIMIT: 연령인증이 필요한 채널
MAX_CHANNELS_LIMIT: 사용자가 추가할 수 있는 카카오톡 채널의 최대 수를 넘어선 경우
ERROR: 카카오톡 채널 PAPI 내부 서버 오류

참고: 하나의 채널 추가 요청이 실패한 경우에는 응답의 에러 코드로 원인 확인
X
curl -v -X POST "http://kapi.kakao.com/v2/internal/talk/channels/add" \
-H "Authorization: OTP ${OTP_TOKEN}"
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 객체입니다. 요청 실패 시 에러 코드에서 원인을 확인합니다.

이름설명필수
AuthorizationAuthorization: OTP ${OTP_TOKEN}
인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
이름타입설명필수
event_idString일정 IDO
recur_update_typeString반복 일정의 수정 범위
  • ALL: 전체 일정
  • THIS: 이 일정만
  • THIS_AND_FOLLOWING: 이 일정과 이후 모든 일정

주의: 반복 일정인 경우 필수
X
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_otp_tokenStringAPI 호출 서비스 앱의 OTP 토큰O
target_idString사용자 IDO
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
O
event_idString일정 IDO
recur_update_typeString반복 일정의 수정 범위
  • ALL: 전체 일정
  • THIS: 이 일정만
  • THIS_AND_FOLLOWING: 이 일정과 이후 모든 일정

주의: 반복 일정인 경우 필수
X
이름타입설명필수
event_idString삭제한 일정 ID

주의: 반복 일정이 아닌 경우 필수
X
  • 파라미터
    • 일정 ID(event_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 토큰(target_otp_token)
    • 사용자 ID(target_id)
    • 사용자 ID 타입(target_id_type): 회원번호(user_id)
    • 일정 ID(event_id)
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"
// 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를 포함합니다. 요청 실패 시 에러 코드에서 원인을 확인합니다.

이름설명필수
AuthorizationAuthorization: OTP ${OTP_TOKEN}
인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
이름타입설명필수
event_idString공개 일정 IDO
calendar_idString사용자 캘린더 ID(기본값: primary)X
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
Content-TypeContent-Type: application/x-www-form-urlencoded;charset=utf-8
요청 데이터 타입
O
이름타입설명필수
target_otp_tokenStringAPI 호출 서비스 앱의 OTP 토큰O
target_idString사용자 IDO
target_id_typeStringtarget_id 타입, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
  • talk_id: 카카오톡 회원번호
O
event_idString공개 일정 IDO
calendar_idString사용자 캘린더 ID(기본값: primary)X
이름타입설명필수
event_idString공개 일정 IDO
  • 파라미터
    • 카카오톡 채널 프로필 ID(channel_public_id)
    • 일정 ID(event_id)
    • 사용자 캘린더 ID(calendar_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 토큰(target_otp_token)
    • 카카오톡 채널 프로필 ID(channel_public_id)
    • 일정 ID(event_id)
    • 사용자 캘린더 ID(calendar_id)
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"
// 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회성 동의 여부 확인
이름설명필수
AuthorizationAuthorization: OTP ${OTP_TOKEN}
인증 방식, 서비스 앱에서 1회성 제공 동의로 발급받은 OTP 토큰으로 인증 요청
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
  • 아래 중 하나의 파라미터는 필수 전달해야 합니다.
    • target_otp_token
    • target_app_keytarget_otp_account_id
이름타입설명필수
target_app_keyStringAPI 호출 서비스 앱의 키O(Optional)
target_otp_tokenStringAPI 호출 서비스 앱의 OTP 토큰O(Optional)
target_otp_account_idString사용자 카카오계정 ID
사용자 카카오계정의 상태를 검증하고, 필요 시 사용자 제재가 가능하도록 하기 위해 전달

중요: target_otp_account_id로 요청 시, 해당 사용자의 동의 여부 확인은 불가능하며 카카오계정의 상태 확인만 가능
O(Optional)
target_kakao_agentStringAPI 호출 서비스 앱의 추가 정보, ip 필수 전달

중요: API 제공자 서버에서 REST API로 패시브 연동 API를 호출할 경우, target_app_key와 무관하게 ip를 포함해야 함
참고: KA 헤더 정보
O
quota_propertiesJSONAPI의 쿼터 제한 시 사용한 팩터(Factor)
uri 키(Key)와 quota_uri 값(Value)으로 구성
API플랫폼에 등록한 값만 사용 가능
({"key":"value"} 형식)
(예: {"uri":"/v1/api/talk/profile"})

중요: API 호출 서비스와 사용자가 연결된 경우의 호출과 구분할 수 있도록 quota_properties의 Quota URI를 다르게 지정해 사용할 것
O
extra_propertiesJSONAPI 제공자별로 필요한 추가 정보, {"key":"value"} 형식
추가 검증이나 로그 분석에 필요
X
property_keysString[]target_id로 사용자 인증을 요청하는 경우에만 사용 가능
응답에 추가로 포함할 사용자 ID를 지정하는 데 사용, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
(예: 'property_keys=["user_id","account_id"]')
X
operationString쿼터에 대해 수행할 동작, 아래 중 하나
  • increase: 1 증가
  • decrease: 1 감소
  • add: operand의 수치만큼 쿼터 소모
  • check: 확인
(기본값: increase)

참고: 각 동작의 용도는 아래와 같습니다.
increase, descrease: API 요청에 따라 해당 사용자의 쿼터 소모량을 1 증가 또는 감소시킬 때 사용
  • add: 해당 사용자의 쿼터 소모량을 operand의 수치만큼 소모시킬 때 사용
  • check: 쿼터를 실제로는 소모시키지 않고, operand 파라미터로 전달된 수치만큼 쿼터 소모량을 증가시켰을 때 쿼터 초과 여부를 확인하기 위해 사용
X
operandIntegeroperation 값을 add로 지정한 경우, 증가 또는 감소시킬 쿼터량
operation 값을 check로 지정한 경우, 남은 쿼터에 operand의 수치만큼 쿼터 소모량이 증가했을 때 쿼터 초과 여부를 확인 가능
(기본값: 1)
X
이름설명필수
AuthorizationAuthorization: KakaoAK ${DELEGATOR_APP_ADMIN_KEY}
인증 방식, 플랫폼 앱 어드민 키로 인증 요청
서비스 앱의 권한을 플랫폼 앱이 위임받아 요청하는 방식으로 내부 API 요청 시 사용 가능
필수 파라미터로 1회성 제공 동의로 발급받은 OTP 토큰 전달 필요
1회성 제공 동의를 위한 요청 방식이므로 앱과 사용자를 연결하지 않으며, 연결되지 않은 상태에서도 사용 가능
O
  • 아래 중 하나의 파라미터는 필수 전달해야 합니다.
    • target_otp_token
    • target_app_keytarget_otp_account_id
이름타입설명필수
target_app_keyStringAPI 호출 서비스 앱의 키O(Optional)
target_otp_tokenStringAPI 호출 서비스 앱의 OTP 토큰O(Optional)
target_otp_account_idString사용자 카카오계정 ID
사용자 카카오계정의 상태를 검증하고, 필요 시 사용자 제재가 가능하도록 하기 위해 전달

중요: target_otp_account_id로 요청 시, 해당 사용자의 동의 여부 확인은 불가능하며 카카오계정의 상태 확인만 가능
O(Optional)
target_kakao_agentStringAPI 호출 서비스 앱의 추가 정보, ip 필수 전달

중요: API 제공자 서버에서 REST API로 패시브 연동 API를 호출할 경우, target_app_key와 무관하게 ip를 포함해야 함
참고: KA 헤더 정보
O
quota_propertiesJSONAPI의 쿼터 제한 시 사용한 팩터(Factor)
uri 키(Key)와 quota_uri 값(Value)으로 구성
API플랫폼에 등록한 값만 사용 가능
({"key":"value"} 형식)
(예: {"uri":"/v1/api/talk/profile"})

중요: API 호출 서비스와 사용자가 연결된 경우의 호출과 구분할 수 있도록 quota_properties의 Quota URI를 다르게 지정해 사용할 것
O
extra_propertiesJSONAPI 제공자별로 필요한 추가 정보, {"key":"value"} 형식
추가 검증이나 로그 분석에 필요
X
property_keysString[]target_id로 사용자 인증을 요청하는 경우에만 사용 가능
응답에 추가로 포함할 사용자 ID를 지정하는 데 사용, 아래 중 하나
  • user_id: 회원번호
  • account_id: 카카오계정 ID
(예: 'property_keys=["user_id","account_id"]')
X
operationString쿼터에 대해 수행할 동작, 아래 중 하나
  • increase: 1 증가
  • decrease: 1 감소
  • add: operand의 수치만큼 쿼터 소모
  • check: 확인
(기본값: increase)

참고: 각 동작의 용도는 아래와 같습니다.
increase, descrease: API 요청에 따라 해당 사용자의 쿼터 소모량을 1 증가 또는 감소시킬 때 사용
  • add: 해당 사용자의 쿼터 소모량을 operand의 수치만큼 소모시킬 때 사용
  • check: 쿼터를 실제로는 소모시키지 않고, operand 파라미터로 전달된 수치만큼 쿼터 소모량을 증가시켰을 때 쿼터 초과 여부를 확인하기 위해 사용
X
operandIntegeroperation 값을 add로 지정한 경우, 증가 또는 감소시킬 쿼터량
operation 값을 check로 지정한 경우, 남은 쿼터에 operand의 수치만큼 쿼터 소모량이 증가했을 때 쿼터 초과 여부를 확인 가능
(기본값: 1)
X
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}"}'

도움이 되었나요?