본문 바로가기 메뉴 바로가기

Kakao i Account::API 레퍼런스::Adapter Agent API

페이지 이동경로

Adapter Agent API

Adapter Agent 서버와 카카오 i 서비스 간의 연동을 위해 고객사는 Adapter Agent API를 직접 구현해야 합니다.

표Adapter Agent API 목록
Capability API 명 설명
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 getResponsibilities 직책 정보를 제공
getPositions 직위 정보를 제공
getChangedOrgunits 특정 시점부터 API 호출 시점까지의 추가, 변경, 비활성화가 일어난 조직도 목록을 제공
getValidOrgunits API 요청 시점에서 유효한 조직도 전체 목록을 제공
- getChangedOrgunits 구현 시 구현 필요
SSO Capability generateSsoUrl SSO URL 제공
DRM Capability authenticate 파일 타입 확인 및 DRM 파일인 경우, 사용자의 접근 권한 확인
decrypt 파일 타입 확인 및 DRM 파일인 경우, 사용자의 접근 권한 확인 및 DRM 해제 요청

Agent Capability

Agent Capability는 Adapter Agent 서버의 설정 정보와 같은 메타데이터를 제공하는 API의 모음입니다. Agent Capability에는 다음과 같은 API가 있습니다.

표Agent Capability 목록
API 명 설명
getAgentCapabilities Adapter Agent 서버에 구현된 Capability 정보를 카카오 i 서비스 시스템에 제공
reportError 카카오 i 서비스 시스템으로부터 오류 정보를 수신

getAgentCapabilities

Adapter Agent 서버에 구현된 기능 정보를 제공하는 API입니다. 카카오 i 서비스 시스템은 각 Adapter Agent 서버가 어떤 기능을 구현했는지에 대한 정보가 필요할 때 해당 API를 호출합니다.

Request

Request Syntax

코드예제getAgentCapabilities Request Syntax 

curl GET '{{ADAPTER_AGENT_DOMAIN}}/api/agent/v0/getAgentCapabilities' \
--header 'Content-Type: application/json' \
--header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}' \

표API 호출 방식
메서드 요청 URL
GET /api/agent/v0/getAgentCapabilities

Request Header

표getAgentCapabilities Request Header
파라미터 타입 필수 여부 설명
Kep-OrgLoginType String 필수 법인의 로그인 방식 별 고유 ID로 Adapter API 호출에 활용됨
ex) ID xxxxxxx
X-Request-Id String 선택 요청마다 고유한 Key 값으로 디버깅에 활용됨

Response

Response Elements

표getAgentCapabilities Response Elements
필드 타입 필수 여부 설명
_code Integer 필수 HTTP 상태 코드 3자리(공통 상태 코드 참고)
_message String 필수 응답 메시지
capabilities String[] 필수 Adapter Agent 서버가 구현한 기능 목록

Sample Code

코드예제Agent Capability와 User Capability 구현 시(HTTP 상태 코드: 200) 

{
  "_code": 200,
  "_message": "ok",
  "capabilities": ["agent", "user"]
}

reportError

Adapter Agent 서버가 오류 정보를 전달받는 API입니다. 카카오 i 서비스 시스템은 각 Adapter Agent 서버로부터 응답을 받아 로직을 수행하는 도중 오류가 발생하면 해당 API를 호출합니다.

Request

코드예제reportError Request Syntax 

curl POST '{{ADAPTER_AGENT_DOMAIN}}/api/agent/v0/reportError' \
--header 'Content-Type: application/json' \
--header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}' \
--data-raw '{
    "code": {Error Code},
    "message": {오류 메시지},
    "capability": {오류가 발생한 Capability},
    "data": {오류 추가정보}
}'

표API 호출 방식
메서드 요청 URL
POST /api/agent/v0/reportError

Request Header

표reportError Request Header
파라미터 타입 필수 여부 설명
Kep-OrgLoginType String 필수 법인의 로그인 방식 별 고유 ID로 Adapter API 호출에 활용됨
ex) ID xxxxxxx
X-Request-Id String 선택 요청마다 고유한 Key 값으로 디버깅에 활용됨

Request Body

표reportError Request Body
파라미터 타입 필수 여부 설명
code Integer 필수 오류 코드
message String 필수 오류 메시지
capability String 필수 오류가 발생한 Capability
data Object 선택 오류 추가정보

Response

Response Elements

표reportError Response Elements
필드 타입 필수 여부 설명
_code Integer 필수 HTTP 상태 코드 3자리(공통 상태 코드 참고)
_message String 필수 응답 메시지

Sample Code

코드예제Adapter Agent 서버가 오류 정보를 성공적으로 수신 

{
  "_code": 200,
  "_message": "ok"
}

User Capability

User Capability는 사용자 정보에 대한 기능을 제공하는 API 모음입니다.

표User Capability 목록
API 명 설명
getValidUsers API 호출 시점을 기준으로 카카오 i 서비스 시스템을 사용할 수 있는 사용자 목록 제공
getChangedUsers 정보 변경, 활성화 및 비활성화가 일어난 사용자 목록 제공
- 특정 시점부터 API 호출 시점까지
getUserMetadata 사용자 정보의 메타데이터와 사용자 정보 동기화에 대한 옵션 정보를 제공

getValidUsers

카카오 i 계정 서버에서 현재 재직 중인 사용자 목록이 필요할 때 호출합니다. API 호출 시점을 기준으로 재직 중인 모든 사용자 목록을 반환합니다.

Request

코드예제getValidUsers Request Syntax 

curl GET '{{ADAPTER_AGENT_DOMAIN}}/api/user/v0/getValidUsers?page_number={pagination index}&page_size={한 페이지 당 자료 개수}' \
--header 'Content-Type: application/json' \
--header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}'

표API 호출 방식
메서드 요청 URL
GET /api/user/v0/getValidUsers

Request Header

표getValidUsers Request Header
파라미터 타입 필수 여부 설명
Kep-OrgLoginType String 필수 법인의 로그인 방식 별 고유 ID로 Adapter API 호출에 활용됨
ex) ID xxxxxxx
X-Request-Id String 선택 요청마다 고유한 Key 값으로 디버깅에 활용됨

Request Parameters

표getValidUsers Request Parameters
파라미터 타입 필수 여부 설명
page_number Integer 필수 Pagination Index로 페이지 시작 번호는 1
page_size Integer 필수 페이지 한 개 당 자료의 개수

Response

Response Elements

표getValidUsers Response Elements
필드 타입 필수 여부 설명
_code Integer 필수 HTTP 상태 코드 3자리(공통 상태 코드 참고)
_message String 필수 응답 메시지
total_pages Integer 필수 총 페이지 수
total_elements Integer 필수 총 아이템 수
size Integer 필수 한 페이지의 최대 아이템 수
number Integer 필수 현재 페이지 인덱스
number_of_elements Integer 필수 현재 페이지의 아이템 개수
is_last Boolean 필수 마지막 페이지 여부
is_first Boolean 필수 첫 페이지 여부
Object[] 필수 사용자 정보 목록
status String 필수 사용자의 상태 값
- 해당 API에서는 ACTIVE로 고정
identifiers String[] 필수 사용자의 계정 시스템 내 고유 식별자 목록
- 퇴사자를 포함하여 고유해야 함
- 카카오워크를 사용하는 법인은 사용자별 고유한 이메일(Email) 정보가 identifiers에 반드시 포함되어야 함
name String 필수 이름
nickname String 선택 닉네임
email String 선택 이메일 주소
- 카카오워크를 사용하는 법인은 해당 필드를 필수로 설정
email_verification String 선택 이메일 인증 상태 고정값
- 카카오워크를 사용하는 법인은 해당 필드를 필수로 설정
VERIFIED: 인증됨
TO_VERIFY: 인증 필요
telephone_international String 선택 국가코드를 포함한 형식에 맞춘 전화번호
telephone_for_display String 선택 표시용 전화번호
telephone_verification String 선택 전화번호 인증 상태 고정값
VERIFIED: 인증됨
TO_VERIFY: 인증 필요
UNVERIFIED: 미인증

Object[] 선택 다른 전화번호 목록
- MOBILE, FIXED_LINE 또는 IPT_MOBILE 타입
type String 필수 전화번호 타입 고정값
MOBILE: 휴대폰
FIXED_LINE: 유선전화
IPT_MOBILE: 휴대폰 IP Telephony
international String 필수 국가코드를 포함한 전화번호
display String 선택 표시용 전화번호
verification String 필수 전화번호 인증 상태 고정값
VERIFIED: 인증됨
TO_VERIFY: 인증 필요
UNVERIFIED: 미인증
Object[] 선택 다른 전화번호 목록
- IPT 타입(유선)일 경우
type String 필수 전화번호 타입 고정값
- IPT: IP Telephony
number String 필수 내부용 전화번호
display String 선택 표시용 전화번호
birthday String 선택 "MM-DD"
is_lunar Boolean 선택 음력 여부
gender String 선택 성별 고정값
MALE: 남성
FEMALE: 여성
UNKNOWN: 알 수 없음
photo_url String 선택 프로필 사진 이미지 주소
- URL Encoding 필수
password String 선택 초기 비밀번호
- 카카오 i 계정 타입이 “카카오 i 연동 계정” 일 경우에 해당 필드는 필수로 사용
- 다른 타입에서는 사용하지 않음

비밀번호 생성 규칙은 다음과 같음
- 형식: 영문 소문자 + 숫자 + 특수문자 조합
- 입력 가능 특수문자(31개): ! " # $%& '()*+,-./:;<=>?@^_`{|}=>?
- 연속 숫자 3자 이상 불가(ex. 123, 789)
- 생년월일 4자리 불가
- 전화번호 8자리 불가
- 동일 문자 3회 이상 반복 불가(ex. aaa)
- 이메일의 아이디, 이메일주소 불가
- 키보드 연속 문자열 불가(ex. qwerty)
privacy_scope String 선택 개인정보 제 3자 제공 고정값
ALL(기본값): 전체 동의, 내/외부 조직 모두 정보 제공
ORGANIZATION: 조직 내 동의, 내부 조직에만 정보 제공, 외부 조직에는 미제공
account_categories String[] 선택 해당 유저가 속한 계정 분류 목록(getUserMetadata API의 응답필드인 account_categories 내 필수 포함)
Object 선택 사용자에 대한 추가 정보
Object 선택 orgUnit Capability 관련 추가 정보
Object[] 선택 사용자의 소속 부서 정보 목록
code String 필수 사용자의 소속 부서 코드
- getValidOrgUnits API의 code 사용
is_main Boolean 필수 대표 부서 여부
- true: 사용자의 대표 부서인 경우
- departments의 아이템 중 하나만 is_main이 true이어야 함
is_leader Boolean 필수 부서장(리더) 여부
responsibility_code String 선택 사용자의 직책 코드
- getResponsibilities API의 code 사용
- 직책이 있을 경우에만 사용
- null: 직책이 없는 경우
position_code String 선택 사용자의 직위 코드
- getPositions API의 code 사용
- 직위가 있을 경우에만 사용
- null: 직위가 없는 경우
meta Object 선택 메타데이터
Object 선택 user Capability 관련 추가 정보
display_identifier String 선택 해당 사용자의 고유 이메일이 없는 경우, 카카오워크에 표시할 고유 식별자
- 해당 값 존재시, 이메일 사용 불가
- 조직 내, display_identifier 설정 필수

Sample Code

다음은 page_number=2와 page_size=500을 요청하여, Pagination을 통해 총 5,555개의 total_elements를 12개의 페이지로 나눈 것 중 두 번째 페이지를 조회한 예제입니다.

코드예제getValidUsers 응답(HTTP 상태 코드: 200) 

{
  "_code": 200,
  "_message": "ok",
  "total_pages": 12,
  "total_elements": 5555,
  "size": 500,
  "number": 2,
  "number_of_elements": 500,
  "is_last": false,
  "is_first": false,
  "contents": [
    {
      "status": "ACTIVE",
      "identifiers": ["test.kim", "087217", "test.kim@dktechin.com"],
      "name": "테스트",
      "nickname": "테스트",
      "email": "test.kim@dktechin.com",
      "email_verification": "TO_VERIFY",
      "telephone_international": "+82 10-1234-5678",
      "telephone_for_display": "010-1234-5678 내선 5",
      "telephone_verification": "TO_VERIFY",
      "more_telephones": [
        {
          "type": "MOBILE",
          "international": "+82 10-1111-2222",
          "display": "010-1111-2222",
          "verification": "TOVERIFY"
        },
        {
          "type": "FIXED_LINE",
          "international": "+82 31-3333-4444",
          "display": "031-3333-4444",
          "verification": "TOVERIFY"
        },
        {
          "type": "IPT_MOBILE",
          "international": "+82 10-5555-6666",
          "display": "010-5555-6666",
          "verification": "TOVERIFY"
        },
        {
          "type": "IPT",
          "display": "개발 1팀",
          "number": "123456789"
        },
        "..."
      ],
      "birthday": "01-01",
      "gender": "MALE",
      "is_lunar": false,
      "photo_url": ""
    },
    {
      "status": "ACTIVE",
      "identifiers": ["test.park", "012345", "test.park@dktechin.com"],
      "name": "테스트",
      "nickname": "테스트",
      "email": "test.park@dktechin.com",
      "email_verification": "TO_VERIFY",
      "telephone_international": "+82 10-8765-4321",
      "telephone_for_display": "010-8765-4321 휴대용",
      "telephone_verification": "TO_VERIFY",
      "more_telephones": [
        {
          "type": "FIXED_LINE",
          "international": "+82 31-2222-5555",
          "display": "031-2222-5555",
          "verification": "TOVERIFY"
        },
        {
          "type": "IPT",
          "display": "개발 2팀",
          "number": "987654321"
        },
        "..."
      ],
      "birthday": "01-01",
      "gender": "FEMALE",
      "is_lunar": false,
      "photo_url": ""
    },
    "..."
  ]
}

getChangedUsers

카카오 i 계정 서버에서 정해진 시간에 주기적으로 해당 API를 호출합니다. basis_time부터 현재 시간까지의 신규등록/삭제/정보변경이 발생한 모든 사용자의 목록을 Pagination을 적용하여 반환합니다.

Request

코드예제getChangedUsers Request Syntax 

curl GET '{{ADAPTER_AGENT_DOMAIN}}/api/user/v0/getChangedUsers?basis_time={YYYYMMDDHHmm}&page_number={pagination index}&page_size={한 페이지 당 자료 개수}' \
--header 'Content-Type: application/json' \
--header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}'

표API 호출 방식
메서드 요청 URL
GET /api/user/v0/getChangedUsers

Request Header

표getChangedUsers Request Header
파라미터 타입 필수 여부 설명
Kep-OrgLoginType String 필수 법인의 로그인 방식 별 고유 ID로 Adapter API 호출에 활용됨
ex) ID xxxxxxx
X-Request-Id String 선택 요청마다 고유한 Key 값으로 디버깅에 활용됨

Request Parameters

표getChangedUsers Request Parameters
파라미터 타입 필수 여부 설명
basis_time String 필수 변경 기준 시각
- Format: YYYYMMDDHHmm
- TimeZone: UTC
page_number Integer 필수 Pagination Index로 페이지 시작 번호는 1
page_size Integer 필수 페이지 한 개 당 자료의 개수

Response

Response Elements

표getChangedUsers Response Elements
파라미터 타입 필수 여부 설명
_code Integer 필수 HTTP 상태 코드 3자리(공통 상태 코드 참고)
_message String 필수 응답 메시지
total_pages Integer 필수 총 페이지 수
total_elements Integer 필수 총 아이템 수
size Integer 필수 한 페이지의 최대 아이템 수
number Integer 필수 현재 페이지 인덱스
number_of_elements Integer 필수 현재 페이지의 아이템 개수
is_last Boolean 필수 마지막 페이지 여부
is_first Boolean 필수 첫 페이지 여부
Object[] 필수 사용자 정보 목록
status String 필수 변경 구분 고정값
REGISTERED: 등록됨
UPDATED: 업데이트됨
DELETED: 삭제됨 (7일의 삭제 유예기간 제공, 구 UNREGISTERED)
HARD_DELETE: 영구 삭제됨
identifiers String[] 필수 사용자의 계정 시스템 내 고유 식별자 목록
- 퇴사자를 포함하여 고유해야 함
- 카카오워크를 사용하는 법인은 사용자별 고유한 이메일(Email) 정보가 identifiers에 반드시 포함되어야 함
name String 필수 이름
nickname String 선택 닉네임
email String 선택 이메일 주소
- 카카오워크를 사용하는 법인은 해당 필드를 필수로 설정
email_verification String 선택 이메일 인증 상태 고정값
- 카카오워크를 사용하는 법인은 해당 필드를 필수로 설정
VERIFIED: 인증됨
TO_VERIFY: 인증 필요
telephone_international String 선택 국가코드를 포함한 형식에 맞춘 전화번호
telephone_for_display String 선택 표시용 전화번호
telephone_verification String 선택 전화번호 인증 상태 고정값
VERIFIED: 인증됨
TO_VERIFY: 인증 필요
UNVERIFIED: 미인증
Object[] 선택 다른 전화번호 목록
- MOBILE, FIXED_LINE 또는 IPT_MOBILE 타입
type String 필수 전화번호 타입 고정값
MOBILE: 휴대폰
FIXED_LINE: 유선전화
IPT_MOBILE: 휴대폰 IP Telephony
international String 필수 국가코드를 포함한 전화번호
display String 선택 표시용 전화번호
verification String 필수 전화번호 인증 상태 고정값
VERIFIED: 인증됨
TO_VERIFY: 인증 필요
UNVERIFIED: 미인증
Object[] 선택 다른 전화번호 목록
- IPT 타입(유선)일 경우
type String 필수 전화번호 타입 고정값
- IPT: IP Telephony
number String 필수 내부용 전화번호
display String 선택 표시용 전화번호
birthday String 선택 "MM-DD"
is_lunar Boolean 선택 음력 여부
gender String 선택 성별 고정값
MALE: 남성
FEMALE: 여성
UNKNOWN: 알 수 없음
photo_url String 선택 프로필 사진 이미지 주소
- URL Encoding 필수
password String 선택 초기 비밀번호
- 카카오 i 계정 타입이 “카카오 i 연동 계정” 일 경우에 해당 필드는 필수로 사용
- 다른 타입에서는 사용하지 않음

비밀번호 생성 규칙은 다음과 같음
- 형식: 영문 소문자 + 숫자 + 특수문자 조합
- 입력 가능 특수문자(31개): ! " # $%& '()*+,-./:;<=>?@^_`{|}=>?
- 연속 숫자 3자 이상 불가(ex. 123, 789)
- 생년월일 4자리 불가
- 전화번호 8자리 불가
- 동일 문자 3회 이상 반복 불가(ex. aaa)
- 이메일의 아이디, 이메일주소 불가
- 키보드 연속 문자열 불가(ex. qwerty)
privacy_scope String 선택 개인정보 제 3자 제공 고정값
ALL(기본값): 전체 동의, 내/외부 조직 모두 정보 제공
ORGANIZATION: 조직 내 동의, 내부 조직에만 정보 제공, 외부 조직에는 미제공
account_categories String[] 선택 해당 유저가 속한 계정 분류 목록(getUserMetadata API의 응답필드인 account_categories 내 필수 포함)
Object 선택 사용자에 대한 추가 정보
Object 선택 Orgunit Capability 관련 추가 정보
Object[] 선택 사용자의 소속 부서 정보 목록
code String 필수 사용자의 소속 부서 코드
- getValidOrgUnits API의 code 사용
is_main Boolean 필수 대표 부서 여부
is_leader Boolean 필수 부서장(리더) 여부
responsibility_code String 필수 사용자의 직책 코드
- getResponsibilities API의 code 사용
- 직책이 있을 경우에만 사용
- null: 직책이 없는 경우
position_code String 선택 사용자의 직위 코드
- getPositions API의 code 사용
- 직위가 있을 경우에만 사용
- null: 직위가 없는 경우
meta Object 선택 메타데이터
Object 선택 user Capability 관련 추가 정보
display_identifier String 선택 해당 사용자의 고유 이메일이 없는 경우, 카카오워크에 표시할 고유 식별자
- 해당 값 존재시, 이메일 사용 불가
- 조직 내, display_identifier 설정 필수

Sample Code

다음은 page_number=2와 page_size=500을 요청하여, Pagination을 통해 총 5,555개의 total_elements를 12개의 페이지로 나눈 것 중 두 번째 페이지를 조회한 예제입니다.

코드예제getChangedUsers 응답(HTTP 상태 코드: 200) 

{
  "_code": 200,
  "_message": "ok",
  "total_pages": 3,
  "total_elements": 1111,
  "size": 500,
  "number": 3,
  "number_of_elements": 111,
  "is_last": true,
  "is_first": false,
  "contents": [
    {
      "status": "REGISTERED",
      "identifiers": ["test.kim", "087217", "test.kim@dktechin.com"],
      "name": "테스트",
      "nickname": "테스트",
      "email": "test.kim@dktechin.com",
      "email_verification": "TO_VERIFY",
      "telephone_international": "+82 10-1234-5678",
      "telephone_for_display": "010-1234-5678 내선 5",
      "telephone_verification": "TO_VERIFY",
      "more_telephones": [
        {
          "type": "MOBILE",
          "international": "+82 10-1111-2222",
          "display": "010-1111-2222",
          "verification": "TOVERIFY"
        },
        {
          "type": "FIXED_LINE",
          "international": "+82 31-3333-4444",
          "display": "031-3333-4444",
          "verification": "TOVERIFY"
        },
        {
          "type": "IPT_MOBILE",
          "international": "+82 10-5555-6666",
          "display": "010-5555-6666",
          "verification": "TOVERIFY"
        },
        {
          "type": "IPT",
          "display": "개발 1팀",
          "number": "123456789"
        },
        "..."
      ],
      "birthday": "01-01",
      "gender": "MALE",
      "is_lunar": false,
      "photo_url": ""
    },
    {
      "status": "UPDATED",
      "identifiers": ["test.park", "012345", "test.park@dktechin.com"],
      "name": "테스트",
      "nickname": "테스트",
      "email": "test.park@dktechin.com",
      "email_verification": "TO_VERIFY",
      "telephone_international": "+82 10-8765-4321",
      "telephone_for_display": "010-8765-4321 휴대용",
      "telephone_verification": "TO_VERIFY",
      "more_telephones": [
        {
          "type": "FIXED_LINE",
          "international": "+82 31-2222-5555",
          "display": "031-2222-5555",
          "verification": "TOVERIFY"
        },
        {
          "type": "IPT",
          "display": "개발 2팀",
          "number": "987654321"
        },
        "..."
      ],
      "birthday": "01-01",
      "gender": "FEMALE",
      "is_lunar": false,
      "photo_url": ""
    },
    {
      "status": "DELETED",
      "identifiers": ["test.lee", "057575", "test.lee@dktechin.com"],
      "name": "테스트",
      "nickname": "테스트",
      "email": "test.lee@dktechin.com",
      "email_verification": "TO_VERIFY",
      "telephone_international": "+82 10-1234-4321",
      "telephone_for_display": "010-1234-4321 외선 1",
      "telephone_verification": "TO_VERIFY",
      "birthday": "01-01",
      "gender": "FEMALE",
      "is_lunar": false,
      "photo_url": ""
    },
    "..."
  ]
}

getUserMetadata

카카오 i 계정 서버에서 사용자의 메타정보가 필요한 시점에 해당 API를 호출합니다. 변경불가 사용자 정보 필드, 동기화 시 사용자 필터링 규칙 등 사용자 메타 정보를 제공합니다.

Request

코드예제getUserMetadata Request Syntax 

curl GET '{{ADAPTER_AGENT_DOMAIN}}/api/user/v0/getUserMetadata' \
--header 'Content-Type: application/json' \
--header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}'

표API 호출 방식
메서드 요청 URL
GET /api/user/v0/getUserMetadata

Request Header

표getUserMetadata Request Header
파라미터 타입 필수 여부 설명
Kep-OrgLoginType String 필수 법인의 로그인 방식 별 고유 ID로 Adapter API 호출에 활용됨
ex) ID xxxxxxx
X-Request-Id String 선택 요청마다 고유한 Key 값으로 디버깅에 활용됨

Response

Response Elements

표getUserMetadata Response Elements
필드 타입 필수 여부 설명
_code Integer 필수 HTTP 상태 코드 3자리(공통 상태 코드 참고)
_message String 필수 응답 메시지
Object 필수 프로필 정보
Object 필수 개인정보 수정 가능 여부
name Boolean 필수 이름 수정 가능 여부
nickname Boolean 필수 닉네임 수정 가능 여부
email Boolean 필수 이메일 수정 가능 여부
telephone Boolean 필수 전화번호 수정 가능 여부
Object 선택 전화번호 수정 가능 여부
- more_telephones를 이용할 경우
mobile Boolean 필수 휴대폰 수정 가능 여부
- telephone과 동일
fixed_line Boolean 필수 유선번호 수정 가능 여부
birthday Boolean 필수 생일 수정 가능 여부
gender Boolean 필수 성별 수정 가능 여부
photo_url Boolean 필수 사진주소 수정 가능 여부
is_lunar Boolean 필수 음력 여부
Object[] 필수 동기화 옵션 관련 목록
display_name String 필수 사용자 동기화 설정 화면에 노출할 옵션명
value String 필수 옵션의 고유값
account_categories String[] 선택 권한을 부여할 수 있는 계정 분류 목록

Sample Code

Adapter Agent 서버와 연동한 계정체계의 사용자 정보 수정 정책이 photo_url만 수정 가능하고, 카카오 i 계정 관리자의 계정 연동 설정 화면에 동기화 옵션으로 ‘정직원 제외’ 옵션을 노출하는 경우입니다.

코드예제getUserMetadata 응답(HTTP 상태 코드: 200) 

{
  "_code": 200,
  "_message": "ok",
  "profile": {
    "editability": {
      "name": false,
      "nickname": true,
      "email": false,
      "telephone": true,
      "telephones": {
        "moblie": false,
        "fixed_line": false
      },
      "birthday": false,
      "is_lunar": false,
      "gender": false,
      "photo_url": true
    }
  },
  "synchronize_options": [
    {
      "display_name": "정직원 제외",
      "value": "except_full_time_employee"
    },
    {
      "display_name": "계약 제외",
      "value": "except_contract"
    },
    {
      "display_name": "협력업체 제외",
      "value": "except_subcontract"
    },
    {
      "display_name": "업무용 계정 제외",
      "value": "except_business_account"
    }
  ]
}

Login Capability

Login Capability는 로그인 연동과 관련된 기능을 제공하는 API 모음입니다. Login Capability에는 다음과 같은 API가 있습니다.

표Login Capability 목록
API 명 설명
identifyUser 입력받은 아이디(ID)와 패스워드(PW) 등이 올바른지 확인
extractUser 사용자에 대한 추가 정보를 카카오 i 서비스 시스템에 제공

identifyUser

ID/PW 기반 로그인 인증 결과를 반환하는 API입니다.

Request

코드예제identifyUser Request Syntax 

curl POST '{{ADAPTER_AGENT_DOMAIN}}/api/login/v0/identifyUser' \
--header 'Content-Type: application/json' \
--header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}' \
--data-raw '{
    "identifier": {유저 ID},
    "password": {유저 PW},
    "extra": {부가 정보}
}'

표API 호출 방식
메서드 요청 URL
POST /api/login/v0/identifyUser

Request Header

표identifyUser Request Header
파라미터 타입 필수 여부 설명
Kep-OrgLoginType String 필수 법인의 로그인 방식 별 고유 ID로 Adapter API 호출에 활용됨
ex) ID xxxxxxx
X-Request-Id String 선택 요청마다 고유한 Key 값으로 디버깅에 활용됨

Request Body

표identifyUser Request Body
파라미터 타입 필수 여부 설명
identifier String 필수 사용자 로그인 시 입력한 식별자
password String 필수 암호(평문)
Object 선택 로그인 관련 추가 정보
user_ip String 선택 로그인한 사용자의 origin-IP
user_agent String 선택 HTTP 사용자 에이전트(User Agent) 값

Sample Code

코드예제카카오워크에서 test.a 계정이 로그인 시도 

{
  "identifier": "test.a",
  "password": "test",
  "extra": {
    "user_ip": "172.0.0.1",
    "user_agent": "Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; rv:11.0) like Gecko KakaoWork/windows/1.2.0.1476/-"
  }
}

Response

Response Elements

표identifyUser Response Elements
필드 타입 필수 여부 설명
_code Integer 필수 HTTP 상태 코드 3자리(공통 상태 코드 참고)
_message String 필수 응답 메시지
result String 필수 authentication 결과 코드 고정값
SUCCESS: 인증 성공
FAILURE: 인증 실패
LOCKED: 계정 잠김
UNKNOWN: 알 수 없음
reason String 필수 result에 대한 원인(이유) 메시지
user_principal Object 선택 사용자 로그인 증명 정보를 자유롭게 노출
- SSO Capability를 구현 시 해당 필드는 필수로 설정
extra Object 선택 추가 정보

Sample Code

코드예제ID, Password, userIP(선택)이 유효한 경우(HTTP 상태 코드: 200) 

{
  "result": "SUCCESS",
  "reason": "AUTH_SUCCESS",
  "_code": 200,
  "_message": "OK"
}

코드예제ID, Password가 유효하지 않을 경우(HTTP 상태 코드: 200, \_code: 401) 

{
  "result": "FAILURE",
  "reason": "AUTH_FAIL",
  "_code": 401,
  "_message": "Unauthorized"
}

코드예제계정이 잠긴 경우(HTTP 상태 코드: 200, \_code: 403) 

{
  "result": "LOCKED",
  "reason": "ACCOUNT_LOCKED",
  "_code": 403,
  "_message": "Forbidden"
}

extractUser

로그인 정합성 및 회원정보 조회를 위한 API입니다.

Request

코드예제OAuth 2.0 로그인 기반의 Request Syntax 

curl POST '{{ADAPTER_AGENT_DOMAIN}}/api/login/v0/extractUser' \
--header 'Content-Type: application/json' \
--header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}' \
--data-raw '{
   "state": {사용자 로그인 상태},
   "payload": {
       "authorization_code": {ADAPTER_AGENT에서 발급받은 CODE}
   }
}'

코드예제SAML 2.0 로그인 기반의 Request Syntax 

curl POST '{{ADAPTER_AGENT_DOMAIN}}/api/login/v0/extractUser' \
--header 'Content-Type: application/json' \
--header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}' \
--data-raw '{
   "state": {사용자 로그인 상태},
   "payload": {
       "response_id": {SAML 2.0 RESPONSE ID},
       "name_id": {SAML 2.0 NAME ID}
   }
}'

표API 호출 방식
메서드 요청 URL
POST /api/login/v0/extractUser

Request Header

표extractUser Request Header
파라미터 타입 필수 여부 설명
Kep-OrgLoginType String 필수 법인의 로그인 방식 별 고유 ID로 Adapter API 호출에 활용됨
ex) ID xxxxxxx
X-Request-Id String 선택 요청마다 고유한 Key 값으로 디버깅에 활용됨

Request Body

표extractUser OAuth 2.0 Request Body
파라미터 타입 필수 여부 설명
state String 필수 사용자의 로그인 상태에 대한 고유값
Object 필수 로그인 방식(OAuth 2.0, SAML 2.0 등)별 추가정보
authorization_code String 선택 고객사의 OAuth 2.0 인증 시스템을 통해 발급 받은 authorization_code
표extractUser SAML 2.0 Request Body
파라미터 타입 필수 여부 설명
state String 필수 사용자의 로그인 상태에 대한 고유값
Object 필수 로그인 방식(OAuth 2.0, SAML 2.0 등)별 추가정보
response_id String 필수 SAML 2.0 요청(Response) ID 값
name_id String 필수 SAML 2.0 이름(Name) ID 값
attributes Object[] 선택 SAML 2.0 관련 추가정보
key String 필수 SAML 2.0 관련 추가정보 Key 값
ex) mail
value Object[] 필수 SAML 2.0 관련 추가정보 Value 값
ex) ["test_client@example.com", "test_client_2@example.com"]

Sample Code

코드예제OAuth 2.0 로그인 기반의 OrgLoginType 

{
  "state": "aek2n4kd",
  "payload": {
    "authorization_code": "xcoiv98y3md22vwsuye3kch"
  }
}

코드예제SAML 2.0 로그인 기반의 OrgLoginType 

{
        "state": "96NBpaHONW9djSZvpO0XGFoVqIPQ8oEsyXjyXyX38aaVX7ozcscFyHL8v7W2mzbQ",
        "payload": {
                "response_id": "PHNhbWxwOlJlc3BvbnNlI ... lc3BvbnNlPg==",
                "name_id": "test_client@example.com",
                "attributes": {
                        "mail": ["test_client@example.com", "test_client_2@example.com"],
                        "id":  ["test_client", "test_client_2"]
                        ...
                }
        }
}

Response

Response Elements

표extractUser Response Elements
필드 타입 필수 여부 설명
_code Integer 필수 HTTP 상태 코드 3자리(공통 상태 코드 참고)
_message String 필수 응답 메시지
Object 필수 해당 로그인의 인증 고유 정보
state String 필수 Request Body에 전달된 state 값
- 사용자의 로그인 상태 고유값
Object 필수 로그인한 사용자의 정보
identifiers String[] 필수 사용자의 계정 시스템 내 고유 식별자 목록
- 퇴사자를 포함하여 고유해야 함
- 카카오워크를 사용하는 법인은 사용자별 고유한 이메일(Email) 정보가 identifiers에 반드시 포함되어야 함
name String 필수 이름
nickname String 선택 닉네임
email String 선택 이메일 주소
- 카카오워크를 사용하는 법인의 경우에 해당 필드는 필수 값으로 설정되는 정보
telephone_international String 선택 국가코드를 포함한 형식에 맞춘 전화번호
telephone_for_display String 선택 표시용 전화번호
Object[] 선택 다른 전화번호 목록
- MOBILE 또는 FIXED_LINE 타입일 경우
type String 필수 전화번호 타입 고정값
MOBILE: 휴대폰
FIXED_LINE: 유선전화
international String 필수 국가코드를 포함한 전화번호
display String 선택 표시용 전화번호
verification String 필수 전화번호 인증 상태 고정값
VERIFIED: 인증됨
TO_VERIFY: 인증 필요
UNVERIFIED: 미인증
Object[] 선택 다른 전화번호 목록
- IPT 타입일 경우
type String 필수 전화번호 타입 고정값
- IPT: IP Telephony
number String 필수 내부용 전화번호
display String 선택 표시용 전화번호
birthday String 선택 "MM-DD"
is_lunar Boolean 선택 음력 여부
gender String 선택 성별 고정값
MALE: 남성
FEMALE: 여성
UNKNOWN: 알 수 없음
photo_url String 선택 프로필 사진 이미지 주소
- URL Encoding 필수
user_principal Object 선택 사용자 로그인 증명 정보를 자유롭게 노출
- SSO Capability를 구현한 경우, 해당 필드는 필수 값으로 설정되는 정보

Sample Code

코드예제extractUser API Request 정보로 사용자를 식별 성공한 경우(HTTP 상태 코드: 200) 

{
  "_code": 200,
  "_message": "OK",
  "authentication": {
    "state": "a3nsh1aakdfe"
  },
  "user_profile": {
    "identifiers": ["test.lee", "057575", "test.lee@dktechin.com"],
    "name": "테스트",
    "nickname": "테스트",
    "email": "test.lee@dktechin.com",
    "email_verification": "TO_VERIFY",
    "telephone_international": "+82 10-1234-5678",
    "telephone_for_display": "010-1234-5678 내선 5",
    "telephone_verification": "TO_VERIFY",
    "more_telephones": [
      {
        "type": "MOBILE",
        "international": "+82 10-1111-2222",
        "display": "010-1111-2222",
        "verification": "TOVERIFY"
      },
      {
        "type": "FIXED_LINE",
        "international": "+82 31-3333-4444",
        "display": "031-3333-4444",
        "verification": "TOVERIFY"
      },
      {
        "type": "IPT",
        "display": "개발 1팀",
        "number": "123456789"
      },
      "..."
    ],
    "birthday": "01-01",
    "gender": "FEMALE",
    "is_lunar": false,
    "photo_url": ""
  }
}

orgUnit Capability

표orgUnit Capability 목록
API 명 설명
getResponsibilities 직책 정보를 제공
getPositions 직위 정보를 제공
getChangedOrgunits 특정 시점부터 API 호출 시점까지의 추가, 변경, 비활성화가 일어난 조직도 목록 제공
getValidOrgunits API 요청 시점에서 유효한 조직도 전체 목록 제공

getResponsibilities

카카오워크 서버에서 현재 사용되는 직책 정보가 필요할 때 호출됩니다. API 호출 시점을 기준으로 사용 중인 모든 직책 목록을 반환합니다.

Request

코드예제getResponsibilities Request Syntax 

curl GET '{{ADAPTER_AGENT_DOMAIN}}/api/orgunit/v0/getResponsibilities?page_number={pagination index}&page_size={한 페이지 당 자료 개수}' \
--header 'Content-Type: application/json' \
--header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}'

표API 호출 방식
메서드 요청 URL
GET /api/orgunit/v0/getResponsibilities

Request Header

표getResponsibilities Request Header
파라미터 타입 필수 여부 설명
Kep-OrgLoginType String 필수 법인의 로그인 방식 별 고유 ID로 Adapter API 호출에 활용됨
ex) ID xxxxxxx
X-Request-Id String 선택 요청마다 고유한 Key 값으로 디버깅에 활용됨

Request Parameters

표getResponsibilities Request Parameters
파라미터 타입 필수 여부 설명
page_number Integer 필수 Pagination Index로 페이지 시작 번호는 1
page_size Integer 필수 페이지 한 개 당 자료의 개수

Response

Response Elements

표getResponsibilities Response Elements
필드 타입 필수 여부 설명
_code Integer 필수 HTTP 상태 코드 3자리(공통 상태 코드 참고)
_message String 필수 응답 메시지
total_pages Integer 필수 총 페이지 수
total_elements Integer 필수 총 아이템 수
size Integer 필수 한 페이지의 최대 아이템 수
number Integer 필수 현재 페이지 인덱스
number_of_elements Integer 필수 현재 페이지의 아이템 개수
is_last Boolean 필수 마지막 페이지 여부
is_first Boolean 필수 첫 페이지 여부
Object[] 필수 responsibility(직책) 목록
code String 필수 직책 코드(unique)
level Integer 필수 직책 레벨
- 값이 낮을수록 높은 직책
- level은 직책 간 정렬에 사용되므로 중복은 허용되지 않음
name String 필수 직책명

Sample Code

다음은 page_number=2와 page_size=500을 요청하여, Pagination을 통해 총 5,555개의 total_elements를 12개의 페이지로 나눈 것 중 두 번째 페이지를 조회한 예제입니다.

코드예제getResponsibilities 응답(HTTP 상태 코드: 200) 

{
        "_code": 200,
        "_message": "ok",
        "total_pages": 12,
        "total_elements": 5555,
        "size": 500,
        "number": 2,
        "number_of_elements": 500,
        "is_last": false,
        "is_first": false,
        "contents": [
                {
                        "code": "1",
                        "level": 1,
                        "name": "대표이사"
                },
                {
                        "code": "2",
                        "level": 2,
                        "name": "실장"
                }, ...
        ]
}

getPositions

카카오워크 서버에서 현재 사용되는 직위 정보가 필요할 때 호출됩니다. API 호출 시점을 기준으로 사용 중인 모든 직위 목록을 반환합니다.

Request

코드예제getPositions Request Syntax 

curl GET '{{ADAPTER_AGENT_DOMAIN}}/api/orgunit/v0/getPositions?page_number={pagination index}&page_size={한 페이지 당 자료 개수}' \
--header 'Content-Type: application/json' \
--header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}'

표API 호출 방식
메서드 요청 URL
GET /api/orgunit/v0/getPositions

Request Header

표getPositions Request Header
파라미터 타입 필수 여부 설명
Kep-OrgLoginType String 필수 법인의 로그인 방식 별 고유 ID로 Adapter API 호출에 활용됨
ex) ID xxxxxxx
X-Request-Id String 선택 요청마다 고유한 Key 값으로 디버깅에 활용됨

Request Parameters

표getPositions Request Parameters
파라미터 타입 필수 여부 설명
page_number Integer 필수 Pagination Index로 페이지 시작 번호는 1
page_size Integer 필수 페이지 한 개 당 자료의 개수

Response

Response Elements

표getPositions Response Elements
필드 타입 필수 여부 설명
_code Integer 필수 HTTP 상태 코드 3자리(공통 상태 코드 참고)
_message String 필수 응답 메시지
total_pages Integer 필수 총 페이지 수
total_elements Integer 필수 총 아이템 수
size Integer 필수 한 페이지의 최대 아이템 수
number Integer 필수 현재 페이지 인덱스
number_of_elements Integer 필수 현재 페이지의 아이템 개수
is_last Boolean 필수 마지막 페이지 여부
is_first Boolean 필수 첫 페이지 여부
Object[] 필수 Position(직위) 목록
code String 필수 직위 코드(unique)
level Integer 필수 직위 레벨
- 값이 낮을수록 높은 직위
- level은 직위 간 정렬에 사용될 값이라 중복이 있으면 안 됨
name String 필수 직위명

Sample Code

다음은 page_number=2와 page_size=500을 요청하여, Pagination을 통해 총 5,555개의 total_elements를 12개의 페이지로 나눈 것 중 두 번째 페이지를 조회한 예제입니다.

코드예제getPositions 응답(HTTP 상태 코드: 200) 

{
        "_code": 200,
        "_message": "ok",
        "total_pages": 12,
        "total_elements": 5555,
        "size": 500,
        "number": 2,
        "number_of_elements": 500,
        "is_last": false,
        "is_first": false,
        "contents": [
                {
                        "code": "1",
                        "level": 1,
                        "name": "부장"
                },
                {
                        "code": "2",
                        "level": 2,
                        "name": "과장"
                }, ...
        ]
}

getChangedOrgunits

카카오워크 서버에서 정해진 시간에 주기적으로 해당 API를 호출합니다. basis_time부터 현재 시간까지의 신규등록/삭제/정보변경이 발생한 모든 조직도 목록을 Pagination을 적용하여 반환합니다.

Request

코드예제getChangedOrgunits Request Syntax 

curl GET '{{ADAPTER_AGENT_DOMAIN}}/api/orgunit/v0/getChangedOrgunits?basis_time={YYYYMMDDHHmm}&page_number={pagination index}&page_size={한 페이지 당 자료 개수}' \
--header 'Content-Type: application/json' \
--header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}'

표API 호출 방식
메서드 요청 URL
GET /api/orgunit/v0/getChangedOrgunits

Request Header

표getChangedOrgunits Request Header
파라미터 타입 필수 여부 설명
Kep-OrgLoginType String 필수 법인의 로그인 방식 별 고유 ID로 Adapter API 호출에 활용됨
ex) ID xxxxxxx
X-Request-Id String 선택 요청마다 고유한 Key 값으로 디버깅에 활용됨

Request Parameters

표getChangedOrgunits Request Parameters
파라미터 타입 필수 여부 설명
basis_time String 필수 변경 기준 시각
- Format: YYYYMMDDHHmm
- TimeZone: UTC
page_number Integer 필수 Pagination Index로 페이지 시작 번호는 1
page_size Integer 필수 페이지 한 개 당 자료의 개수

Response

Response Elements

표getChangedOrgunits Response Elements
필드 타입 필수 여부 설명
_code Integer 필수 HTTP 상태 코드 3자리(공통 상태 코드 참고)
_message String 필수 응답 메시지
total_pages Integer 필수 총 페이지 수
total_elements Integer 필수 총 아이템 수
size Integer 필수 한 페이지의 최대 아이템 수
number Integer 필수 현재 페이지 인덱스
number_of_elements Integer 필수 현재 페이지의 아이템 개수
is_last Boolean 필수 마지막 페이지 여부
is_first Boolean 필수 첫 페이지 여부
Object[] 필수 Orgunit 목록
status String 필수 변경 구분 고정값
REGISTERED: 등록됨
UPDATED: 업데이트됨
DELETED: 삭제됨 (구 UNREGISTERED)
code String 필수 조직 코드(unique)
- 다른 정보가 달라도 code가 같으면 같은 조직이라 판단
- 값으로 #은 사용할 수 없음
name String 필수 조직명
parent_code String 필수 상위 조직 코드
- 최상위 조직은 보통 워크스페이스명으로 같은 name으로 하나만 존재할 수 있음
- 최상위 조직의 parent_code 값은 #으로 고정
is_private Boolean 필수 비공개 조직 여부
- 비공개 조직은 하위 조직도 모두 비공개 상태여야 함
- 비공개 조직 관련 기능은 개발 예정이므로, 개발 완료 시점까지는 false 값으로 고정
order Integer 필수 같은 상위 조직을 가진 조직간의 정렬 순서
- 작은 값일수록 상위에 위치
- 0부터 순차적으로 지정해야 함(0, 1, 2 ...)
Object 선택 추가 정보
meta Object 선택 메타데이터

Sample Code

다음은 page_number=2와 page_size=500을 요청하여, Pagination을 통해 총 5,555개의 total_elements를 12개의 페이지로 나눈 것 중 두 번째 페이지를 조회한 예제입니다.

코드예제getChangedOrgunits 응답(HTTP 상태 코드: 200) 

{
        "_code": 200,
        "_message": "ok",
        "total_pages": 12,
        "total_elements": 5555,
        "size": 500,
        "number": 2,
        "number_of_elements": 500,
        "is_last": false,
        "is_first": false,
        "contents": [
                {
                        "status": "REGISTERED",
                        "code": "21",
                        "name": "카카오게임즈",
                        "parent_code": "#",
                        "is_private": false,
                        "order": 0
                },
                {
                        "status": "UPDATED",
                        "code": "GMS00000045",
                        "name": "캐주얼&광고사업본부",
                        "parent_code": "GMS00000159",
                        "is_private": false,
                        "order": 3
                },
                {
                        "status": "DELETED",
                        "code": "GMS00000046",
                        "name": "서버셀",
                        "parent_code": "1234",
                        "is_private": false,
                        "order": 1
                }, ...
        ]
}

getValidOrgunits

getChangedOrgunits 구현 시에 반드시 구현해야 하는 API이며, 카카오워크 서버에서 현재 사용되는 조직도 정보가 필요할 때 호출됩니다. API 호출 시점을 기준으로 사용 중인 모든 조직도 목록을 반환합니다.

주의
getValidOrgunits 구현 시, 응답(Response)에 최상위 조직을 반드시 포함해야 합니다.

Request

코드예제getValidOrgunits Request Syntax 

curl GET '{{ADAPTER_AGENT_DOMAIN}}/api/orgunit/v0/getValidOrgunits?page_number={pagination index}&page_size={한 페이지 당 자료 개수}' \
--header 'Content-Type: application/json' \
--header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}'

표API 호출 방식
메서드 요청 URL
GET /api/orgunit/v0/getValidOrgunits

Request Header

표getValidOrgunits Request Header
파라미터 타입 필수 여부 설명
Kep-OrgLoginType String 필수 법인의 로그인 방식 별 고유 ID로 Adapter API 호출에 활용됨
ex) ID xxxxxxx
X-Request-Id String 선택 요청마다 고유한 Key 값으로 디버깅에 활용됨

Request Parameters

표getValidOrgunits Request Parameters
파라미터 타입 필수 여부 설명
page_number Integer 필수 Pagination Index로 페이지 시작 번호는 1
page_size Integer 필수 페이지 한 개 당 자료의 개수

Response

Response Elements

표getValidOrgunits Response Elements
필드 타입 필수 여부 설명
_code Integer 필수 HTTP 상태 코드 3자리(공통 상태 코드 )
_message String 필수 응답 메시지
total_pages Integer 필수 총 페이지 수
total_elements Integer 필수 총 아이템 수
size Integer 필수 한 페이지의 최대 아이템 수
number Integer 필수 현재 페이지 인덱스
number_of_elements Integer 필수 현재 페이지의 아이템 개수
is_last Boolean 필수 마지막 페이지 여부
is_first Boolean 필수 첫 페이지 여부
Object[] 필수 Orgunit 목록
status String 필수 ACTIVE로 고정
code String 필수 조직 코드(unique)
- 다른 정보가 달라도 code가 같으면 같은 조직이라 판단
- 값으로 #은 사용할 수 없음
name String 필수 조직명
parent_code String 필수 상위 조직 코드
- 최상위 조직은 보통 워크스페이스명으로 같은 name으로 하나만 존재할 수 있음
- 최상위 조직의 parent_code 값은 #으로 고정
is_private Boolean 필수 비공개 조직 여부
- 비공개 조직은 하위 조직도 모두 비공개 상태여야 함
- 비공개 조직 관련 기능은 개발 예정이므로, 개발 완료 시점까지는 false 값으로 고정
order Integer 필수 같은 상위 조직을 가진 조직간의 정렬 순서
- 작은 값일수록 상위에 위치
- 0부터 순차적으로 지정해야 함(0, 1, 2 ...)
Object 선택 추가 정보
meta Object 선택 메타데이터

Sample Code

다음은 page_number=2와 page_size=500을 요청하여, Pagination을 통해 총 5,555개의 total_elements를 12개의 페이지로 나눈 것 중 두 번째 페이지를 조회한 예제입니다.

코드예제getValidOrgunits 응답(HTTP 상태 코드: 200) 

{
        "_code": 200,
        "_message": "ok",
        "total_pages": 12,
        "total_elements": 5555,
        "size": 500,
        "number": 2,
        "number_of_elements": 500,
        "is_last": false,
        "is_first": false,
        "contents": [
                {
                        "status": "ACTIVE",
                        "code": "21",
                        "name": "카카오게임즈",
                        "parent_code": "#",
                        "is_private": false,
                        "order": 0
                },
                {
                        "status": "ACTIVE",
                        "code": "GMS00000045",
                        "name": "캐주얼&광고사업본부",
                        "parent_code": "GMS00000159",
                        "is_private": false,
                        "order": 3
                }, ...
        ]
}

SSO Capability

SSO Capability는 카카오 i 서비스를 통해 Single sign-on (SSO)을 이용하기 위해 Adapter Agent 서버의 SSO관련 데이터를 제공하는 API의 모음입니다. SSO Capability에는 다음과 같은 API가 있습니다.

표orgUnit Capability 목록
API 명 설명
generateSsoUrl SSO URL 제공

generateSsoUrl

Adapter Agent 서버에서 유효한 SSO url을 제공하는 API입니다. 카카오 i 서비스 시스템은 각 유저가 SSO기능을 이용할 때 해당 API를 호출합니다.

Request

코드예제generateSsoUrl Request Syntax 

curl POST '{{ADAPTER_AGENT_DOMAIN}}/api/orgunit/v0/genereateSsoUrl' \
--header 'Content-Type: application/json' \
--header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}' \
--data-raw '{
    "target_url": {요청한 URL 주소}
}'

표API 호출 방식
메서드 요청 URL
POST /api/sso/v0/generateSsoUrl

Request Header

표generateSsoUrl Request Header
파라미터 타입 필수 여부 설명
Kep-OrgLoginType String 필수 법인의 로그인 방식 별 고유 ID로 Adapter API 호출에 활용됨
ex) ID xxxxxxx
X-Request-Id String 선택 요청마다 고유한 Key 값으로 디버깅에 활용됨

Request Body

표generateSsoUrl Request Body
파라미터 타입 필수 여부 설명
target_url String 필수 요청한 URL 주소
user_principal Object 선택 고객사의 사용자 식별 정보
extra Object 선택 IP 및 고객 기기 정보

Sample Code

코드예제카카오 i 서비스 시스템을 통한 generateSsoUrl 요청 

{
        "target_url": "http://test.com/abcde",
        "user_principal": {
          ...
        },
        "extra": {
                "user_ip": "172.0.0.1",
                "user_agent": "Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; rv:11.0) like Gecko KakaoWork/windows/1.2.0.1476/-"
        }
}

Response

Response Elements

표generateSsoUrl Response Elements
필드 타입 필수 여부 설명
_code Number 필수 HTTP 상태 코드 3자리(공통 상태 코드 참고)
_message String 필수 응답 메시지
sso_url String 필수 Adapter Agent 서버에서 제공하는 SSO url 주소
result String 필수 결과 구분 고정값
AUTHENTICATED: 인가됨
UNAUTHORIZED: 비인증됨
FORBIDDEN: 거부됨
INVALID: 유효하지 않음
UNKNOWN: 그 외
user_principal Object 선택 고객사의 사용자 식별 정보

Sample Code

코드예제generateSsoUrl 정상 응답(HTTP 상태 코드: 200) 

{
        "_code": 200,
        "_message": "ok",
        "sso_url": "http://abc.com/abc",
        "result": "AUTHORIZED",
        "user_principal": {
          ...
        }
}

DRM Capability

DRM Capability는 카카오 i 서비스에서 고객사의 DRM 권한 확인 및 해제 요청을 하기 위해 Adapter Agent 서버에서 제공하는 API 모음입니다. DRM Capability는 다음과 같습니다.

표DRM Capability 목록
API 명 설명
authenticate 파일 타입 확인 및 DRM 파일인 경우, 사용자의 접근 권한 확인
decrypt 파일 타입 확인 및 DRM 파일인 경우, 사용자의 접근 권한 확인 및 DRM 해제 요청

authenticate

Adapter Agent 서버에서 파일 확인 후 DRM 파일인 경우, 사용자의 접근 권한을 확인하는 API입니다. 카카오 i 서비스 시스템은 각 사용자별 파일 접근 권한을 확인하기 위해 해당 API를 호출합니다.

Request

Request Syntax

코드예제authenticate Request Syntax 

curl POST '{{ADAPTER_AGENT_DOMAIN}}/api/drm/v0/authenticate' \
--header 'Content-Type: application/json' \
--header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}' \
--header 'Kep-File-Id: {file ID}' \
--data-raw '{
   "user_principal": {사용자 식별정보}
}'

표API 호출 방식
메서드 요청 URL
POST /api/drm/v0/authenticate

Request Header

표authenticate Request Header
파라미터 타입 필수 여부 설명
Kep-OrgLoginType String 필수 법인의 로그인 방식 별 고유 ID로 Adapter API 호출에 활용됨
ex) ID xxxxxxx
Kep-File-Id String 필수 DRM 권한을 확인하는 파일 ID
ex) xxxxxxx
X-Request-Id String 선택 요청마다 고유한 Key 값으로 디버깅에 활용됨

Request Body

표authenticate Request Body
파라미터 타입 필수 여부 설명
user_principal Object 필수 고객사의 사용자 식별 정보
- 사용자를 식별할 수 있는 주요 정보
extra Object 선택 추가 정보
- 사용자를 식별할 수 있는 추가 정보(ex. 사용자 IP 정보, 사용자 브라우저 정보)

Sample Code

코드예제카카오 i 서비스 시스템을 통한 authenticate 요청 

{
        "user_principal": {
          ...
        },
        "extra": {
                "user_ip": "172.0.0.1",
                "user_agent": "Mozilla/5.0 (Windows NT 10.0; WOW64; Trident/7.0; rv:11.0) like Gecko KakaoWork/windows/1.2.0.1476/-"
        }
}

Response

Response Header

표authenticate Response Header
필드 타입 필수 여부 설명
Kep-AgentSession String 필수 Adapter Agent 서버에서 DRM 해제를 요청한 세션을 구분하는 세션 ID
ex) DSID xxxxxx
Kep-File-Id String 필수 해당 파일 ID
ex) xxxxxx
Kep-File-Type String 필수 해당 파일 type 고정값
DRM: DRM 해제가 필요한 파일 (DRM으로 암호화된 파일)
PLAIN: 일반 파일(DRM으로 암호화되지 않은 일반 파일)
N/A: 알 수 없는 파일(ex. 파일 ID를 알 수 없는 경우)
표authenticate Response Element
필드 타입 필수 여부 설명
_code Integer 필수 HTTP 상태 코드 3자리(공통 상태 코드 참고)
_message String 필수 응답 메시지
result String 필수 결과 코드 고정값
DRM: DRM 해제가 필요한 파일
SUCCESS: 사용자가 파일 접근 권한이 있으며, decrypt API를 호출할 수 있음
FAILURE: 사용자가 파일 접근 권한 없음
PLAIN: 일반 파일
FAILURE: DRM 해제가 불필요한 일반 파일
N/A: 알 수 없는 파일
SUCCESS: 성공 응답을 전달하여 카카오 i 서비스가 decrypt API를 통해 DRM 해제 요청 하도록 유도
reason String 필수 result에 대한 원인(이유) 메시지
extra Object 선택 추가 정보

Sample Code

코드예제authenticate 정상 응답(HTTP 상태 코드: 200) 

{
        "_code": 200,
        "_message": "ok",
        "result": "OK",
        "extra": {
          ...
        }
}

decrypt

Adapter Agent 서버에서 해당 파일 확인 후 DRM 파일인 경우, 사용자 권한 확인 및 DRM 해제 요청을 하는 API입니다. 해당 API 사용 시 Decrypt 요청 결과만 확인할 수 있습니다. DRM 해제는 Adapter API를 통해 수행됩니다.

Request

Request Syntax

코드예제decrypt Request Syntax 

curl POST '{{ADAPTER_AGENT_DOMAIN}}/api/drm/v0/decrypt' \
--header 'Content-Type: multipart/form-data' \
--header 'Kep-OrgLoginType: ID {YOUR_KEP_ORG_LOGIN_TYPE_ID}' \
--header 'Kep-File-Id: {file ID}' \
--header 'Kep-AgentSession: DSID {이전 인증에서 요청한 SESSION ID}' \
--form 'file=@"{파일 절대주소}"'

표API 호출 방식
메서드 요청 URL
POST /api/drm/v0/decrypt

Request Header

표decrypt Request Header
파라미터 타입 필수 여부 설명
Content-Type String 필수 multipart/form-data
Kep-OrgLoginType String 필수 법인의 로그인 방식 별 고유 ID로 Adapter API 호출에 활용됨
ex) ID xxxxxxx
Kep-File-Id String 필수 DRM 권한을 확인하는 파일 ID
ex) xxxxxxx
Kep-AgentSession String 필수 Adapter Agent 서버에서 DRM 해제요청을 한 세션을 구분하기 위한 세션 ID
Adapter Agent 내에서 해당 user_principal과 매핑해서 관리해야 파일 접근권한 체크가능
ex) DSID xxxxxx
X-Request-Id String 선택 요청마다 고유한 Key 값으로 디버깅에 활용됨

Request Body

표decrypt Request Body
파라미터 타입 필수 여부 설명
file Binary 필수 DRM을 해제할 파일 스트림

Sample Code

코드예제카카오 i 서비스 시스템을 통한 decrypt 요청 

...[FILE]...

Response

Response Header

표decrypt Response Header
필드 타입 필수 여부 설명
Kep-AgentSession String 필수 Adapter Agent 서버에서 DRM 해제를 요청한 세션을 구분하는 세션 ID
ex) DSID xxxxxx
Kep-File-Id String 필수 해당 파일 ID
ex) xxxxxx
표authenticate Response Element
필드 타입 필수 여부 설명
_code Integer 필수 HTTP 상태 코드 3자리(공통 상태 코드 참고)
_message String 필수 응답 메시지

Sample Code

코드예제decrypt 정상 응답(HTTP 상태 코드: 200) 

{
  "_code": 200,
  "_message": "ok"
}

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

더 자세한 의견은 contact.dkt@kakaocorp.com 으로 제보해주세요.