Kakao i Account::API 레퍼런스

페이지 이동경로

구현 API 목록

카카오 i 서비스 시스템이 고객사 정보에 접근할 수 있도록 고객사가 구현하는 Adapter Agent API와 카카오 i에서 제공하는 Adapter API로 구분됩니다.

전체 API 목록
분류 Capability API 명 설명
Adapter Agent API (고객사 구현) - - 카카오 i 서비스 시스템이 고객사 정보에 접근할 수 있도록 제공
- Adapter Agent 서버도 함께 구현
Agent Capability getAgentCapabilities Adapter Agent 서버에 구현된 Capability 정보를 카카오 i에 제공
reportError 카카오 i 서비스 시스템으로부터 오류 정보를 수신
User Capability getValidUsers API 호출 시점을 기준으로 카카오 i 서비스 시스템을 사용할 수 있는 사용자 목록 제공
getChangedUsers 정보 변경, 활성화 및 비활성화가 일어난 사용자 목록 제공
- 특정 시점으로부터 API 호출 시점까지
getUserMetadata 사용자 정보의 메타데이터와 사용자 정보 동기화에 대한 옵션 정보를 제공
Login Capability identifyUser 입력받은 아이디(ID)와 패스워드(PW) 등이 올바른지 확인
extractUser 사용자에 대한 추가 정보를 카카오 i에 제공
orgUnit Capability getPositions 직위 정보 제공
getResponsibilities 직책 정보 제공
getChangedOrgunits 특정 시점으로부터 API 호출 시점까지의 추가, 변경, 비활성화가 일어난 조직도 목록 제공
getValidOrgunits API 요청 시점에서 유효한 조직도 전체 목록 제공
- getChangedOrgunits 구현 시 구현 필요
SSO Capability generateSsoUrl SSO URL 제공
- identifyUser API 또는 extractUser API 둘 중 하나를 반드시 구현
- user_principal 필수로 반환
Adapter API
(카카오 i에서 제공)
- getOrgLoginType Adapter Agent 서버를 구현한 고객사의 로그인 방식에 대한 정보를 제공
안내
API 별 작업 흐름과 개발 프로세스에 대한 설명은 카카오 i 계정 개발 프로세스를 참고하시기 바랍니다.

API 공통 가이드

API Request

API 호출 방식

Adapter Agent API와 Adapter API의 호출 방식은 application/json만 허용하며, 파라미터 전달은 아래의 방식을 따릅니다.

API 호출 방식
메서드 구분 파라미터 전달
GET URL 요청 URL에 표기된 쿼리 파라미터
POST Body Request Body에 application/json으로 표현된 데이터

API Response

공통 상태 코드

응답 상태 코드는 API 호출에 대한 실행결과를 의미합니다. 아래의 상태 코드만 응답하고 있으며, 표현되지 않는 응답 상태 코드는 Response Body의 _code 필드에 표현합니다.

응답 상태 코드
상태 코드 설명
200 API 실행 성공
400 4xx 오류
500 503을 제외한 5xx 오류
503 서버 점검 중

공통 Response

Response Body에는 아래의 필드가 항상 포함됩니다.

공통 Response Body
필드 타입 필수 여부 설명
_code Number 필수 HTTP 응답코드 3자리
ex) 200, 400, 401, 500, 503 등
_message String 필수 결과 메시지

코드예제요청 헤더의 필수 값이 누락된 경우(HTTP 상태 코드: 400)

{
    "_code": 400,
    "_message": "Kep-OrgLoginType is not present."
}

코드예제예기치 못한 오류가 발생한 경우(HTTP 상태 코드: 500)

{
    "_code": 500,
    "_message": "Internal server error"
}

코드예제Adapter Agent 서버가 점검 중인 경우(HTTP 상태 코드: 503)

{
    "_code": 503,
    "_message": "Service unavailable"
}

안내
응답 상태 코드와 Response Body의 _code는 각각 다음과 같은 의미로 활용되며, 일반적으로 같은 값으로 설정되어 있지만 경우에 따라 다르게 세팅해야 할 수도 있습니다.

  • 응답 상태 코드: API 호출의 결과 상태 코드
  • _code: API의 비즈니스 로직 수행 결과 코드

필드 타입 표기

Adapter API 와 Adapter Agent API의 요청과 응답은 기본적으로 JSON 타입을 따르며, 추가로 확장된 타입은 아래 표 | 필드 타입 표기를 따릅니다.

필드 타입 표기
타입 표기 설명
{Type}[] 특정 타입의 값을 요소로 갖는 배열(Array)
- 배열 타입의 경우 값이 없을 때 null이 아닌 빈 배열([])로 표현
ex) String[]의 경우 문자열(String) 타입의 값을 요소로 갖는 배열(Array)
Timestamp Unix Time(유닉스 시간)으로 표현된 숫자(Number)
- 시각을 표현하는 용도로 사용

Adapter Agent API

다음은 고객사에서 구현해야 하는 Adapter Agent API의 공통 사항입니다.

API URL

Adapter Agent API URL 구조는 아래와 같습니다.

코드예제Adapter Agent API URL 구조

/api/{capability}/{version}/{API name}

Adapter Agent API URL
필드 타입 필수 여부 설명
Capability String[] 필수 Adapter Agent API 군을 분류하는 기준
- 고객사는 필요에 따라 원하는 Capability만 구현 가능
- 해당 Capability에 속하는 API는 모두 구현해야 함
   ex) User Capability 구현 시에는 getValidUsers, getChangedUsers, getUserMetadata API를 모두 구현해야 함
version String 필수 API 버전 관리를 위한 필드
- 현재 Adapter는 v0만 구현
API name String 필수 API의 이름
ex) getOrgLoginType

Request

공통 Request Header
파라미터 타입 필수 여부 설명
X-Request-Id String 선택 요청마다 고유한 Key 값으로 디버깅에 활용됨

ACL 관리

Adapter 서버는 자신의 ACL(Access Control List)에 IP 주소가 등록되어 있는 Adapter Agent API 서버만 호출합니다. 따라서 Adapter Agent 서버 개발 시 Adapter Agent 서버의 공인 IP 목록을 카카오 i 계정 관리자 화면의 계정연동설정 > OAuth2 메뉴에서 Adapter 호출 정보 설정 항목에 입력해야 합니다. 또한, Adapter 서버는 AdapterAgent 서버의 포트 번호를 80443만 허용하고 있습니다. 80443 이외의 포트 번호로 AdapterAgent 서버를 구축하셔야 한다면 카카오엔터프라이즈의 담당자에게 문의해주시기 바랍니다.

Adapter Agent 서버에서도 Adapter의 서버 주소를 ACL에 등록하여 관리할 수 있습니다.

Adapter IP List
IP 설명
210.109.2.200 Adapter 서비스 공식 NAT IP 주소
안내
Adapter 서버에서 고객사 서버에 구현된 Adapter Agent API를 호출할 경우에 Default Timeout은 5초(5,000 ms)입니다.

Adapter API

카카오 i 서비스 시스템에서 제공하는 Adapter API의 공통 사항입니다.

서버 도메인

Adapter API를 호출하기 위한 서버 도메인을 선택해야 하며, 서버 도메인은 https만 가능합니다.

Adapter 서버 도메인
Phase Host 설명
Sandbox https://adapter.sandbox.kakaoi.ai 개발용 서버
CBT https://adapter.cbt.kakaoi.ai 실제 서비스와 DB를 공유하는 Close Beta Test 서버
Production https://adapter.kakaoi.ai 실제 서비스용 서버

API URL

Adapter API URL 구조는 아래와 같습니다.

코드예제API URL 구조

/api/trust/{capability}/{version}/{API name}

Adapter API URL
파라미터 타입 필수 여부 설명
Capability String[] 필수 Adapter Agent API 군을 분류하는 기준
- 고객사는 필요에 따라 원하는 Capability만 구현 가능
- 해당 Capability에 속하는 API는 모두 구현해야 함
   ex) User Capability 구현 시에는 getValidUsers, getChangedUsers, getUserMetadata API를 모두 구현해야 함
version String 필수 API 버전 관리를 위한 필드
- 현재 Adapter는 v0만 구현
API name String 필수 API의 이름
ex) getOrgLoginType

API 인증

Adapter API는 카카오 i 계정 관리자의 계정 연동 설정 화면에서 생성한 Secret Key와 Adapter Agent 서버의 공인 IP 기반 인증을 수행합니다. Adapter 서버는 HTTP 헤더를 통해 Secret Key와 OrgLoginTypeId를 입력받고, 카카오 i 계정 관리자 화면에 입력된 Adapter Agent 서버의 공인 IP 주소를 확인하여 해당 요청이 어떤 Adapter Agent 서버가 보낸 요청인지 식별하고 인증을 수행합니다.

이러한 인증을 통과하기 위해 HTTP 요청의 Authorization 헤더에 생성한 Secret Key를 설정하고, Kep-OrgLoginType 헤더에 Adapter Agent API 요청으로 전달된 OrgLoginTypeId를 설정합니다. 그리고 카카오 i 계정 관리자 화면의 ‘계정 연동 설정’ 탭에서 Adapter Agent 서버의 공인 IP 주소를 입력합니다.

코드예제CURL 요청

  curl -X GET 'http://adapter.cbt.kakaoi.ai/api/trust/login/v0/getOrgLoginType' \
    --header 'Authorization: KAASK {YOUR_SECRET_KEY}' \
    --header 'Kep-OrgLoginType: ID {YOUR_ORG_LOGIN_TYPE_ID}' \

Request

Adapter API 호출 시 다음의 공통 Request Header가 필요합니다.

공통 Request Header
파라미터 타입 필수 여부 설명
Authorization String 필수 카카오 i 계정 관리자 화면에서 생성한 Secret Key
ex) KAASK xxxxxxxxxx
Kep-OrgLoginType String 필수 Adapter Agent API의 Request Header로 전달된 API 조회 용 법인별 고유 ID
ex) ID xxxxxxxxxx

관련 문서

Adapter Agent Kakao i Account 개발 프로세스 Kakao i Account API 레퍼런스 Kakao i Account

이 문서가 만족스러운 이유를 알려주세요.
이 문서에 아쉬운 점을 알려주세요.
평가해주셔서 감사합니다.

더 자세한 의견은 documentation@kakaoenterprise.com 으로 제보해주세요.