사이드 메뉴
커뮤니케이션
API 제공
어드민 API
레퍼런스
이 문서는 제공 종료된 구버전 어드민 API에 대해 안내합니다. 신규 어드민 API에 대한 자세한 내용은 신규 어드민 API 제공 안내에서 확인할 수 있습니다.
이 문서는 어드민 API 사용에 관한 정보를 안내합니다.
어드민 API는 각 앱의 서비스에 중대한 영향을 미칠 수 있는 설정 기능을 포함하므로, 보안을 위해 2단계의 인증을 요구합니다. 아래는 인증을 포함한 어드민 API의 동작 과정을 표현한 이미지입니다.
위와 같은 인증 절차를 통과하기 위해 어드민 API 요청 시 인증 정보(Authorization)에 1차 인증 정보인 그룹을, 헤더(Header)에 2차 인증 정보인 사용자 정보를 포함해야 합니다. 아래는 각 인증 단계에 대한 상세 안내입니다.
모든 어드민 API 사용자는 그룹에 속해 있습니다. 사용 신청 시 각 사용처는 그룹으로 등록되고, 고유한 그룹 이름과 그룹 토큰을 발급받습니다. 발급받은 그룹 이름과 그룹 토큰을 어드민 API 호출 시 HTTP Basic Authentication 정보로써 전달해야 합니다.
각 그룹은 하나 이상의 사용자로 구성되고, 각 사용자에게 다른 권한을 부여할 수 있습니다. 그룹 내 사용자 개별 인증 수단인 인증 타입은 그룹별로 지정되며, 아래 Header: 2차 인증에서 자세한 인증 수단의 종류를 확인할 수 있습니다.
아래는 1차 인증에 실패한 경우의 응답 예제입니다.
HTTP/2 401Authorization not found.
1차 인증인 그룹 인증 후, 2차 인증으로 그룹 내 각 사용자를 인증합니다. 2차 인증과 그룹 내 사용자의 개별 권한 설정으로 같은 그룹 안에 속해 있더라도 접근 가능한 리소스의 범위를 사용자마다 다르게 할 수 있습니다.
2차 인증은 그룹에 설정된 인증 타입에 따라 수행됩니다. 인증 타입별로 지정된 사용자 정보로 사용자를 인증할 수 있습니다.
인증 타입 설정은 사용 등록 시 API플랫폼에서 요구 사항에 적합한 타입을 선택해 그룹에 적용합니다. 어드민 API 요청 시에는 해당 인증 타입에 맞는 값을 사용해야 합니다. 인증 타입의 종류는 아래 표를 참고합니다.
| 타입 | 설명 |
|---|---|
| KAKAO | ADMIN-API-USERID: ${KAKAO_ACCOUNT_ID}카카오계정 ID로 사용자 인증 |
| KAKAO_BY_ACCESS_TOKEN | ADMIN-API-USERID: ${ACCESS_TOKEN}카카오 로그인으로 발급받은 액세스 토큰으로 사용자 인증 |
| KAKAO_BY_REFRESH_TOKEN | ADMIN-API-USERID: ${REFRESH_TOKEN}리프레시 토큰으로 사용자 인증 |
| KAKAO_BY_ID_TOKEN | ADMIN-API-USERID: ${ID_TOKEN}카카오 로그인 및 OpenID Connect 사용 앱에서 ID 토큰으로 사용자 인증 |
| KAKAO_BY_EMAIL Deprecated | ADMIN-API-USERID: ${KAKAO_ACCOUNT_EMAIL}카카오계정 이메일로 사용자 인증 |
| DEVELOPER | ADMIN-API-USERID: ${DEVELOPER_ID}개발자 계정 ID로 사용자 인증 |
| DEVELOPER_BY_ACCOUNT_ID | ADMIN-API-USERID: ${KAKAO_ACCOUNT_ID}개발자 계정인 카카오계정 ID로 사용자 인증 |
| DEVELOPER_BY_EMAIL Deprecated | ADMIN-API-USERID: ${EMAIL}개발자 계정 이메일로 사용자 인증 |
| APP | ADMIN-API-USERID: ${APP_ID}앱 ID로 사용자 인증 |
| APP_BY_APP_KEY | ADMIN-API-USERID: ${APP_KEY}앱 키로 사용자 인증 |
| KD_DEVELOPER_TOKEN | ADMIN-API-USERID: ${USER_ID}카카오디벨로퍼스 게이트웨이(Gateway)에서 제공하는 정보로 사용자 인증 ${USER_ID}는 개발자 웹사이트의 kd-developer-token 헤더 값과 쿠키 값을 콜론(:)으로 이어 붙인 문자열을 Base64 인코딩한 값(참고:예제) |
| ByPass | ADMIN-API-USERID: ${USER_ID}추가 인증 없이 ADMIN-API-USERID 헤더에 전달된 사용자 정보 사용 |
| STATIC | ADMIN-API-USERID: ${USER_ID}설정에 명시된 사용자 ID로 인증 |
| HelloMIS Internal | 사내 계정 정보로 사용자 인증 |
| HTTP Internal | 외부 서버를 인증에 사용 |
| TOKEN Internal | 다른 인증 타입으로 사용자 인증 후 발급된 토큰 |
| UserDao Internal Deprecated | 어드민 API 사용자 데이터로 사용자 인증 |
아래는 2차 인증에 실패한 경우의 응답 예제입니다.
HTTP/2 401Failed to find the UserId
어드민 API는 카카오 API 플랫폼의 앱은 페이즈별로 등록되므로, 조회 및 수정하려는 앱의 페이즈에 맞게 요청해야 합니다. 아래는 아래 페이즈(Phase)별 호스트(Host) 정보입니다.
| 페이즈 | 호스트 |
|---|---|
| 알파(Alpha) | https://alpha-internal-admin-kapi.kakao.com |
| 샌드박스(Sandbox) | https://sandbox-internal-admin-kapi.kakao.com |
| 베타(Beta) | https://beta-internal-admin-kapi.kakao.com |
| 프로덕션(Production) | https://internal-admin-kapi.kakao.com |
어드민 API는 HTTPS와 POST만 허용합니다. 각 요청은 리소스(Resource), 헤더 및 인증 정보, 데이터를 포함해야 합니다. 아래는 어드민 API 요청 예제입니다.
아래는 각 구성 요소에 대한 안내입니다.
| 항목 | 설명 |
|---|---|
| [A] 접근 대상 리소스 | 어드민 API로 접근할 리소스 |
| [B] 1차 인증 정보 | 1차 인증을 위한 그룹 이름과 그룹 토큰 |
| [C] 2차 인증 정보 | 2차 인증을 위한 사용자 정보 그룹에 부여된 인증 타입에 따라 지정된 인증 수단 사용 |
| [D] 액션 이름 ( name) | 대상 리소스에 취할 상세 동작을 정의한 액션(Action)의 이름 각 API 개발 문서에서 요청 가능한 액션 목록 확인 가능 |
| [E] 페이로드 ( payload) | 조회 조건이나 수정 값과 같은 데이터 어드민 API의 응답은 payload로 전달된 값에 따라 구성됨각 API 개발 문서에서 사용 가능한 키 목록 확인 가능 |
아래는 어드민 API 요청 curl 예제입니다.
curl -v -X POST "https://internal-admin-kapi.kakao.com/app" \-H "Content-Type: application/json; charset=utf-8" \-H "ADMIN-API-META-RENDER: simple" \-u "${GROUP_NAME}:${GROUP_TOKEN}" \-H "ADMIN-API-USERID: ${USER_INFO}" \-d '{"name": "FIND_BY_APP_KEY","payload": {"app_key":"${APP_KEY}"\}}'
각 어드민 API의 응답에 새로운 필드가 추가될 수 있습니다. 응답 처리 구현 시 필드 추가로 인한 에러가 발생하지 않도록 주의해야 합니다.
어드민 API는 기본 응답과 함께 간편 응답의 두 가지 구조로 응답을 제공합니다. 효율적인 API 사용을 위해 응답 유형을 선택해 요청할 수 있습니다.
- 요청 시 전달된
payload를 기반으로 구성되는 기본적인 응답 구조
| 이름 | 타입 | 설명 | 필수 |
|---|---|---|---|
| name | String | 액션 이름 | O |
| payload | Any | 액션 결과로 하위 필드 구성은 API, 액션마다 다름 액션 성공 시: 해당 API 및 액션의 응답으로 지정된 타입의 데이터 포함 액션 실패 시: 실패 원인 안내 | O |
| error | Integer | 액션이 실패한 경우, 실패 원인에 대한 상세 응답 코드 | X |
- 요청 및 액션 성공, 액션 실패, 요청 실패의 세 가지 결과 발생 가능
| 결과 | HTTP 상태 코드 | 설명 |
|---|---|---|
| 요청 및 액션 성공 | 200 | API 요청 및 액션 모두 성공한 경우 응답 본문에 API 및 액션별로 지정된 타입의 데이터 반환 payload 하위 필드에서 필요한 데이터 입수(예: payload.id) |
| 액션 실패 | 200 | API 요청은 성공했으나, 액션이 실패한 경우 응답 본문의 error 필드 유무로 실패 여부 확인 가능응답 코드: 기본 응답에서 상세 에러 코드 확인 |
| 요청 실패 | 200 이외의 숫자 응답 코드: 기본 응답 참고 | HTTP 상태 코드로 실패 원인 안내 |
// HTTP/2 200{"name": "FIND_SIMPLE_APP_BY_APP_KEY","payload": {"id": 977070,"name": "Sample","company": "SampleCompany","icon": "https://k.kakaocdn.net/14/dn/ZSfZPxO70E/DJNC0WsJym1OoiMmo8K5O1/o.jpg","app_type": "KAKAO","category": "Book_Reference","status": "ACTIVE","phase": "NORMAL"}}
// HTTP/2 200{"name": "FIND_SIMPLE_APP_BY_APP_KEY","payload": {"app_key": {"description": "This field is required","message": "${MESSAGE}","args": []}},"error": 412}
// HTTP/2 200{"name": "CREATE_WITH_DEFAULT","payload": {"message": "${MESSAGE}"},"error": 400}
HTTP/2 401Failed to find the UserId
- 헤더에
ADMIN-API-META-RENDER: simple을 포함해 요청
- 응답 본문에 기본 응답의
payload필드 하위 데이터만 포함
- 요청 성공, 실패의 두 가지 결과 발생 가능
| 결과 | HTTP 상태 코드 | 설명 |
|---|---|---|
| 요청 및 액션 성공 | 200 | API 요청 및 액션 모두 성공한 경우 응답 본문에 API 및 액션별로 지정된 타입의 데이터 반환 지정된 타입의 각 키 이름으로 필요한 데이터 입수(예: id) |
| 요청 실패 | 200 이외의 숫자 응답 코드: 간편 응답 참고 | API 요청 또는 액션에 실패한 경우 HTTP 상태 코드로 실패 여부와 원인 확인 가능 응답 본문에 특정 파라미터에 해당하는 필드가 명시된 경우, description와 message로 상세 실패 원인 확인 가능 |
// HTTP/2 200{"id": 977070,"name": "Sample","company": "SampleCompany","icon": "https://k.kakaocdn.net/14/dn/ZSfZPxO70E/DJNC0WsJym1OoiMmo8K5O1/o.jpg","app_type": "KAKAO","category": "Book_Reference","status": "ACTIVE","phase": "NORMAL"}
// HTTP/2 400{"app_key": {"description": "This field is required","message": "${MESSAGE}","args": []}}
// HTTP/2 400{"message": "${MESSAGE}","exception": "com.kakao.capri.commons.service.LimitExceededException"}
HTTP/2 401Failed to find the UserId
기본 응답은 액션 실패 시 payload 및 error 필드로 상세 응답 코드를 반환합니다.
| HTTP 상태 코드 | 에러 | 설명 |
|---|---|---|
| 200 | X | 요청 성공 |
| 200 | 400 | 액션을 지정하지 않았거나, 지정한 액션에 필요한 페이로드가 올바르게 전달되지 않은 경우 액션 수행 대상 서비스에서 예외(Exception)가 발생한 경우 |
| 200 | 404 | 액션 수행 결과에 해당하는 리소스가 존재하지 않는 경우 (예: 앱 ID나 앱 키로 앱 조회 시 해당 앱이 존재하지 않는 경우) |
| 200 | 412 | 파라미터가 유효하지 않은 경우 |
| 200 | 500 | 기타 에러 |
| 401 | X | 1차 인증 또는 2차 인증 실패 |
| 403 | X | API 또는 특정 페이로드에 대한 권한이 없는 경우 |
| 404 | X | 요청 대상 리소스 또는 액션을 찾을 수 없음 리소스를 잘못 지정한 경우 별도 메시지 없이 응답 반환 |
| 500 | X | 서버 에러 또는 내부 오류 |
간편 응답은 HTTP 상태 코드로 실패 원인을 반환합니다.
| HTTP 상태 코드 | 설명 |
|---|---|
| 200 | 요청 및 액션 성공 |
| 400 | 액션 수행 대상 서비스에서 예외(Exception)가 발생한 경우 파라미터가 유효하지 않은 경우 |
| 401 | 1차 인증 또는 2차 인증 실패 |
| 403 | API 또는 특정 페이로드에 대한 권한이 없는 경우 |
| 404 | 액션 수행 결과에 해당하는 리소스가 존재하지 않는 경우 (예: 앱 ID나 앱 키로 앱 조회 시 해당 앱이 존재하지 않는 경우) |
| 500 | 서버 에러 또는 기타 에러 |