이 문서는 카카오 및 공동체에 제공하는 어드민 API에 대해 소개합니다.

어드민 API는 카카오 API 플랫폼의 데이터(앱, 개발자 계정 등)를 등록, 조회, 수정하는 기능을 제공합니다. 어드민 API를 사용하면, 각 서비스의 관리자 사이트에서 카카오디벨로퍼스를 거치지 않고 바로 해당 데이터를 처리하는 기능을 구현할 수 있습니다.

어드민 API 사용 문의와 요청은 [서비스] API플랫폼 아지트에서 할 수 있습니다.

1. 개발자 계정 등록과 앱 생성을 완료합니다.
2. 등록한 앱 정보를 [서비스] API플랫폼 아지트의 [인하우스/제휴 앱 등록 요청] 양식으로 제출해 인하우스 앱으로 등록합니다. 어드민 API 사용 권한은 인하우스 앱만 신청할 수 있습니다.
3. 어드민 API 개발 문서에서 권한을 신청할 API의 이름, URL, 리소스(resource), 액션(action) 정보를 확인 후, 사용할 사용자 인증 방식과 함께 [서비스] API플랫폼 아지트의 어드민 API 사용 신청 양식으로 제출합니다. (참고: 권한 정보)
4. 제공받은 권한에 해당하는 어드민 API를 요청 규격을 준수해 요청합니다. 어드민 API 개발 문서에서 각 API의 사양을 확인하고 테스트할 수 있습니다.

• 어드민 API는 사용 권한을 보유한 앱으로 사내망에서 호출할 수 있습니다.
• 어드민 API는 일반 사용자(End user) 대상 서비스에서 사용할 수 없습니다.
• 어드민 API는 별도로 지정된 요청 규격을 준수해서 요청해야 합니다.
• 어드민 API로 앱 어드민 키는 조회 불가하며, 앱 팀원의 카카오계정 이메일은 마스킹되어 제공될 수 있습니다.
• 장기간 사용하지 않은 어드민 API 사용 권한은 회수될 수 있습니다.
• 어드민 API의 요청, 응답 모델은 언제든지 추가될 수 있습니다.
• 트래픽이 많은 서비스에서는 캐시(Cache) 사용을 고려 해야 합니다.

• 특정 IP에서의 호출만 허용하도록 설정할 수 있습니다. 사용자 인증 방식 중 BYPASS(인증 생략)를 사용하는 경우 반드시 설정해야 합니다. 어드민 API 사용 신청 양식 제출 시 호출을 허용할 IP 주소를 포함해서 설정할 수 있습니다.

어드민 API 개발 문서는 별도 페이지에서 Swagger UI로 제공합니다.

어드민 API 개발 문서에서 각 API의 주요 정보를 확인하고 테스트 호출을 할 수 있습니다. 메뉴별 설명은 아래를 참고합니다.

어드민 API 개발 문서

[A] 메서드, URL, API 이름
[B] 권한 정보
[C] 테스트 호출 버튼
[D] 세부 정보
[E] 예제
[F] 스키마(Schema), 데이터 규격 정보 표시

각 어드민 API의 아래 권한 관련 정보를 표시합니다. 어드민 API 사용 권한은 리소스와 액션 단위로 제공합니다.

• resource, action: 해당 어드민 API의 사용 권한 제어 단위, 권한 신청 시 함께 전달 필요
• requiredDeveloperRole: 해당 항목이 표기된 API는 개발자 계정으로 사용자 인증 시 해당 역할 이상의 멤버만 API 요청 가능, 미표기된 경우 모든 멤버가 요청 가능

어드민 API의 아래 세부 정보를 표시합니다.

• Parameters: 요청 파라미터와 관련 설명, 예제, 스키마
• Response: 응답 필드와 관련 설명, 예제, 스키마

어드민 API 요청 시 준수해야 할 규격 정보에 대해 안내합니다. 항목별 세부 내용을 확인합니다.

• HTTPS(포트 번호: 443)로 사내망에서만 요청 가능
• 요청 대상 페이즈별 호스트로 요청 필요
• 앱 인증과 사용자 인증 필요
• 지정 가능 Content-Type 헤더
  • application/x-www-form-urlencoded
  • application/json
  • multipart/form-data

어드민 API의 페이즈(Phase)별 호스트(Host) 정보입니다. 카카오디벨로퍼스 앱과 개발자 계정은 페이즈별로 등록되므로, 요청 대상의 페이즈에 해당하는 호스트를 사용해야 합니다.

어드민 API는 앱 인증과 사용자 인증을 모두 수행해야 호출할 수 있습니다. 요청 시 각 인증별 지정된 양식의 헤더를 포함해야 합니다. 아래 인증 요청 예제와 항목별 설명을 참고합니다.

# 어드민 API 인증
curl -v -X GET "${ADMIN_API_URL}" \
  -H "Authorization: KakaoAK ${APP_ADMIN_KEY}" \   # 앱 인증
-H "Caller-Authorization: ${CALLER_AUTHORIZATION}" # 사용자 인증

앱을 인증하려면 어드민 API 요청 시 Authorization 헤더에 사용 권한이 있는 인하우스 앱의 어드민 키를 포함해야 합니다. (참고: 예제)

• 어드민 API 사용 권한: 사용 권한 신청으로 획득 가능, 사용 방법 참고
• 어드민 키: 앱 관리 페이지의 [앱] > [어드민 키]에서 확인 가능(참고: 어드민 키)

사용자(Caller) 인증은 어드민 API 요청 시 Caller-Authorization 헤더(참고: 예제)를 아래 인증 수단 중 하나로 전달해야 합니다.

사용자 인증이 불가능한 경우 [서비스] API플랫폼 아지트로 문의합니다.

어드민 API 호출 시 발생할 수 있는 에러 목록입니다.

• 개발 문서(Swagger UI): 전체 어드민 API 사양, 호출 테스트 제공