Admin API
하나의 tenant에 한정된 관리 동작입니다. 계정 생성과 관리, 활성화 제어, MFA 초기화, 라이선스 관리, 그리고 tenant 동작 설정을 다룹니다. tenant를 넘나드는 동작은 Super Admin을 참고합니다. tenant의 감사 기록은 별도 페이지인 Audit logs에 있습니다.
Base URL과 인가
/api/external/v1/admins
이 endpoint들은 ADMIN 역할을 가진 계정으로 발급된 API Key가 필요합니다. 슈퍼 관리자의 키도 통과합니다.
예외가 두 개 있으며 해당 항목에 표시했습니다.
/admins/**의 인가는 역할만으로 결정됩니다. API Key의 scope는 검사하지 않으므로, api:read만 가진 키로도 계정
생성, 용량 변경, 사용자 비활성화, CSV 가져오기, 라이선스 등록이 가능합니다. 관리자 키는 발급 시 지정한 scope와
무관하게 전체 권한 credential로 취급합니다.
외부 API Key로 인증한 POST /admins는 rt가 USER인 계정만 생성할 수 있습니다. ADMIN을 요청하면
USER_013으로 거부됩니다. 다만 일괄 계정 등록에는 같은 제약이 없습니다 -
해당 항목의 경고를 참고합니다.
모든 동작은 호출자 본인의 tenant로 한정됩니다. userSeq를 받는 endpoint는 다른 tenant의 userSeq에 대해
존재하지 않는 경우와 동일하게 USER_005를 반환하므로 계정 존재 여부가 드러나지 않습니다.
페이지네이션
관리자 목록은 cursor 페이지네이션을 씁니다. 페이지 크기로 ps를, 이전 페이지의 마지막 userSeq로 ci를
보냅니다. 값이 없는 nextCursor와 hasNext는 응답에서 생략됩니다.
계정 생성
POST /api/external/v1/admins
multipart/form-data로 보냅니다.
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
ui | string | Yes | 계정 id. 이메일 주소, 최대 25자 |
encPwd | string | Yes | 비밀번호. 8~64자이며 대문자·소문자·숫자·기호를 각 1자 이상 포함 |
un | string | Yes | 표시 이름, 최대 20자 |
tq | long | Yes | 저장 용량 한도(byte) |
rt | string | Yes | 역할. 외부 키는 USER만 보낼 수 있음 |
pif | file | No | 프로필 이미지 |
ct | string | No | 국가 번호. 앞의 더하기 기호 제외, 최대 4자 |
pn | string | No | 전화번호. 구분 기호 제외, 최대 20자 |
ct와 pn은 함께 보내거나 둘 다 생략해야 합니다. 하나만 보내면 USER_027을 반환합니다.
curl -X POST "https://drive.example.com/api/external/v1/admins" \
-H "Authorization: Bearer replace-with-your-api-key" \
-F "ui=user1@example.com" \
-F "encPwd=User1234!" \
-F "un=First user" \
-F "tq=1000000000" \
-F "rt=USER"
새 userSeq를 반환합니다. 이메일 형식이 잘못되면 USER_002, 중복이면 USER_004, 라이선스 좌석이나 가용 용량을
초과하면 USER_013 또는 QUOTA_004를 반환합니다.
계정 조회
GET /api/external/v1/admins/{userSeq}
용량, 역할, 상태, 전화번호, MFA 상태, 등록·수정 이력을 함께 반환합니다. 날짜는 ISO 시각이 아니라 포맷된 문자열입니다.
isActive는 deprecated하위 호환을 위해 유지됩니다. status를 사용합니다.
계정 수정
PATCH /api/external/v1/admins/{userSeq}
multipart/form-data로 보냅니다.
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
un | string | Yes | 표시 이름, 최대 20자 |
tq | long | Yes | 저장 용량 한도(byte) |
ct | string | No | 국가 번호. pn과 함께 보내거나 둘 다 생략 |
pn | string | No | 전화번호. ct와 함께 보내거나 둘 다 생략 |
pif | file | No | 프로필 이미지 |
dpi | boolean | No | 기존 프로필 이미지 삭제 여부. 기본값 false |
sk | string | No | 스토리지 키 |
현재 사용량보다 작은 용량으로 줄이면 USER_014로 거부됩니다.
관리자 목록
GET /api/external/v1/admins
호출자 tenant의 관리자 계정만 조회하며 일반 사용자는 제외합니다.
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
ps | integer | Yes | 페이지 크기, 최소 1 |
ci | long | No | cursor - 이전 페이지의 마지막 userSeq |
s | enum | No | 상태 필터 - active 또는 inactive, 대소문자 무관 |
s에 그 밖의 값을 보내면 USER_019를 반환합니다.
계정 비밀번호 설정
PATCH /api/external/v1/admins/{userSeq}/password
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
newPwd | string | Yes | 새 비밀번호. 8~64자이며 대문자·소문자·숫자·기호를 각 1자 이상 포함 |
현재 비밀번호를 요구하지 않으므로 변경이 아니라 설정에 해당합니다.
활성화와 비활성화
PATCH /api/external/v1/admins/{userSeq}/activate
PATCH /api/external/v1/admins/{userSeq}/deactivate
활성화에 실패하면 USER_017, 비활성화에 실패하면 USER_018을 반환합니다. 본인 계정과 tenant의 기본 관리자
계정은 비활성화할 수 없으며 시도하면 USER_011을 반환합니다.
삭제 대기 처리
PATCH /api/external/v1/admins/{userSeq}/withdraw
계정을 제거하지 않고 삭제 대기 상태로 전환합니다. 본인 계정과 기본 관리자는 대상으로 지정할 수 없으며
USER_012를 반환합니다. 대기 처리에 실패하면 USER_016을 반환합니다. 이후 흐름은
삭제 대기 계정을 참고합니다.
MFA 초기화
PATCH /api/external/v1/admins/users/{userSeq}/mfa/reset
대상 계정의 다중 인증 설정을 해제해 사용자가 다시 등록할 수 있게 합니다. 이 동작은 감사 로그에
USER_TWOFACTOR_RESET으로 기록됩니다. 실패하면 USER_022를 반환합니다.
CSV로 계정 가져오기
GET /api/external/v1/admins/import/csv/sample
POST /api/external/v1/admins/import/csv
먼저 양식을 내려받습니다. 가져오기가 기대하는 열 구성이 이 파일에 정의되어 있습니다.
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
file | file | Yes | 양식 형식의 CSV 파일 |
se | boolean | No | 생성된 각 계정에 안내 메일 발송 |
모든 행이 성공하면 insertCount를 반환합니다.
계정 id 중복, 좌석·용량 초과, 파싱 오류 등으로 한 행이라도 실패하면 응답이 JSON 공통 구조가 아니라 HTTP 400과
text/csv 본문이 됩니다. 반환 파일은 원본 열에 실패 사유 열을 덧붙인 형태입니다. JSON으로 파싱하기 전에
Content-Type을 확인합니다.
사용자 프로필 이미지 조회
GET /api/external/v1/users/{userSeq}/profile-image
이 endpoint만 /admins가 아니라 /users 아래에 있어서 역할 규칙이 아니라 일반 scope 검사가 적용됩니다.
관리자 역할 없이 api:read 또는 api:write를 가진 키로도 호출할 수 있습니다.
이 페이지의 다른 모든 endpoint와 달리, 이 endpoint는 조회를 호출자 tenant로 제한하지 않습니다. 다른 tenant에
속한 userSeq를 지정하면 USER_005가 아니라 그 사용자의 프로필 이미지를 반환합니다. tenant 소속 확인 용도로
쓰지 말고, 누가 이 endpoint에 도달할 수 있는지 정할 때 이 점을 고려합니다.
프로필 이미지가 없는 계정은 USER_008을 반환합니다.
사용자 계정 목록
GET /api/external/v1/admins/users
호출자 tenant에서 USER 역할을 가진 계정을 조회합니다. 관리자와 슈퍼 관리자 계정은 항상 제외되며, 그쪽은
관리자 목록을 사용합니다.
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
ps | integer | Yes | 페이지 크기, 최소 1 |
ci | long | No | cursor - 이전 페이지의 마지막 userSeq |
s | enum | No | 상태 필터 - ACTIVE 또는 INACTIVE. 그 밖의 값은 USER_019 |
u | string | No | 계정 id 부분 일치 검색 |
s를 생략하면 삭제·삭제 대기 상태를 제외한 기본 노출 상태로 조회합니다.
API Key 발급 대상 계정 검색
GET /api/external/v1/admins/users/search
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
sk | string | Yes | 계정 id 또는 표시 이름에 대한 검색 키워드 |
USER 역할이면서 ACTIVE 상태인 계정만 반환합니다. 다른 역할과 상태는 결과에 나타나지 않으므로 API Key를
발급할 계정을 고르는 데 적합합니다.
저장 용량 사용량 조회
GET /api/external/v1/admins/users/{userSeq}/storage-usage
계정의 사용량을 항목별로 나누어 보여줍니다.
| Field | Type | 의미 |
|---|---|---|
totalQuotaBytes | long | 저장 용량 한도 |
totalUsedBytes | long | 총 사용량 |
liveUsedBytes | long | 현재 파일이 차지하는 용량 |
versionUsedBytes | long | 버전 이력이 차지하는 용량 |
trashUsedBytes | long | 휴지통 항목이 차지하는 용량 |
휴지통을 비우거나 버전 이력을 삭제하면 뒤의 두 항목을 회수할 수 있습니다.
계정 보안 로그 조회
GET /api/external/v1/admins/users/{userSeq}/log
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
ps | integer | Yes | 가져올 항목 수 |
ci | long | No | cursor - 이전 페이지의 마지막 userLogSeq |
각 항목은 activityType, ipAddress, region, registerDate와 함께, 사용자가 직접 한 동작인지 관리자가
대행한 동작인지를 알려주는 actorType을 담습니다.
여러 계정의 상태 확인
POST /api/external/v1/admins/users/bulk-status
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
userIds | array | Yes | 조회할 계정 id 목록. 비어 있으면 안 됨 |
일치하는 각 계정의 userSeq, userId, status를 반환합니다.
호출자 tenant에 없는 id는 개별 오류 없이 결과에서 빠집니다. 모든 id가 해석되었다고 가정하지 말고 보낸 목록과 반환된 목록을 대조합니다.
계정 일괄 등록·수정
POST /api/external/v1/admins/users/bulk
한 요청으로 계정을 등록하고 수정합니다. us가 없는 항목은 등록, us가 있는 항목은 수정입니다. 등록 포함 여부와
무관하게 HTTP 상태는 항상 200입니다.
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
users | array | Yes | 등록·수정할 계정 목록. 비어 있으면 안 됨 |
각 항목은 다음을 받습니다.
| Field | Type | 필수 | 설명 |
|---|---|---|---|
us | integer | No | 계정 seq. 생략하면 등록, 값이 있으면 수정 |
ui | string | No | 계정 id, 최대 25자. 등록 시 필수 |
encPwd | string | No | 비밀번호. 8~64자이며 대문자·소문자·숫자·기호를 각 1자 이상 포함. 등록 시 필수 |
un | string | Yes | 표시 이름, 최대 20자 |
tq | long | Yes | 저장 용량 한도(byte). 현재 사용량보다 작게 줄일 수 없음 |
rt | string | No | 역할. 등록 시 필수 |
ct | string | No | 국가 번호. pn과 함께 보내거나 둘 다 생략 |
pn | string | No | 전화번호. ct와 함께 보내거나 둘 다 생략 |
응답은 insertedCount, updatedCount와 등록된 각 계정의 userId·userSeq를 알려줍니다.
POST /admins와 달리 이 endpoint는 rt를 제한하지 않습니다. ADMIN과 SUPER_ADMIN이 그대로 받아들여져 해당
역할로 계정이 생성되므로, 이 endpoint에 도달할 수 있는 관리자 API Key는 새 관리자 계정을 만들 수 있습니다. 이
endpoint를 쓸 수 있는 호출자를 제한하고, 요청을 전달하기 전에 rt를 직접 검증합니다. 알려진 역할이 아닌 값도
깔끔하게 거부되지 않고 HTTP 500으로 실패합니다.
등록 시 필수 항목이 빠지면 USER_026, 비밀번호가 패턴에 맞지 않으면 USER_001, 계정 id가 중복이면 USER_004,
현재 사용량보다 작은 용량으로 줄이면 USER_014를 반환합니다.
계정 즉시 삭제
DELETE /api/external/v1/admins/users/{userSeq}
하드 삭제입니다. 삭제 대기 유예 기간을 전혀 거치지 않으며 복구할 수 없습니다. 본인 계정이나 tenant의 유일한 관리자를 삭제하는 것을 막는 가드도 없습니다. 복구 불가능한 삭제를 의도한 경우가 아니면 삭제 대기 처리를 사용합니다.
삭제 대기 계정
삭제 대기 계정은 예정일까지 기다린 뒤 제거되며, 그전까지는 복원할 수 있습니다.
GET /api/external/v1/admins/users/pending-delete
PATCH /api/external/v1/admins/users/pending-delete/{userSeq}/restore
PATCH /api/external/v1/admins/users/pending-delete/permanent-delete
목록은 다음을 받습니다.
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
ps | integer | Yes | 페이지 크기, 최소 1 |
pdSd | date | No | 삭제 대기 전환 시점 범위 시작. pdEd와 함께 전송 |
pdEd | date | No | 삭제 대기 전환 시점 범위 종료. pdSd와 함께 전송 |
dsSd | date | No | 삭제 예정일 범위 시작. dsEd와 함께 전송 |
dsEd | date | No | 삭제 예정일 범위 종료. dsSd와 함께 전송 |
ci | long | No | cursor - 마지막 userSeq. cv와 함께 전송 |
cv | date | No | cursor - 마지막 pendingDeleteDate. ci와 함께 전송 |
각 항목은 pendingDeleteDate, deleteScheduleTime과 대기 처리를 한 사람을 알려줍니다. status는 항상
PENDING_DELETE입니다.
복원하면 계정이 정상 사용 상태로 돌아갑니다. 삭제 대기 상태가 아닌 계정은 ADMIN_USER_001을 반환합니다.
완전 삭제는 비어 있지 않은 userSeq 배열 ul을 받아 모두 제거합니다. 빈 목록은 REQUEST_001을 반환합니다.
목록에 삭제 대기 상태가 아닌 계정이 하나라도 있으면 일부만 적용되지 않고 요청 전체가 ADMIN_USER_002로
실패하므로, 목록을 다시 읽어 유효한 항목만으로 재시도합니다.
라이선스
Thinkfree Drive 라이선스를 관리하는 endpoint가 셋입니다.
POST /api/external/v1/admins/register/license
GET /api/external/v1/admins/get/license
GET /api/external/v1/admins/get/license/status
라이선스 endpoint는 공통 구조를 쓰지 않습니다. 등록에 성공하면 본문 없이 HTTP 200을 반환하고, 조회 endpoint 둘은
라이선스 필드를 최상위에 그대로 반환합니다. 실패는 {"code": number, "error": "ENUM_NAME"} 형태이며 error는
메시지가 아니라 상수명입니다. 공통 구조 처리기로 파싱하지 않습니다.
GET /admins/get/license/status는 ADMIN이 아니라 USER로 인가되므로 일반 계정의 키로도 라이선스 상태를
읽을 수 있습니다.
라이선스 등록
라이선스 파일을 multipart/form-data의 licenseFile로 보냅니다. 파일 형식이 잘못되면 해당 코드와 함께 HTTP
400, 처리에 실패하면 6999와 함께 HTTP 500, 업로드 읽기에 실패하면 4999와 함께 HTTP 500을 반환합니다.
라이선스 조회
GET /admins/get/license는 발급된 라이선스를 반환합니다.
| Field | Type | 의미 |
|---|---|---|
publisher | string | 발급자. 항상 TF |
CATEGORY | string | TRIAL 또는 PRODUCTION |
LICENSE_TYPE | string | SITE 또는 PERSEAT |
LICENSE_ID | string | 라이선스 식별자 |
CLIENT_NAME | string | 고객사명 |
issuedOn | string | 발급일 |
expiresOn | string | 만료일 |
updatedAt | string | 라이선스 기록이 마지막으로 갱신된 시각 |
spents | integer | 발급 후 경과 일수 |
days | integer | 총 유효 기간(일) |
state | boolean | 현재 라이선스 유효 여부 |
gracePeriod | boolean | 만료 후 최대 8일의 유예 기간 중일 때만 true로 포함 |
paidWhiteLabel | boolean | 유상 화이트라벨 옵션 포함 여부 |
constrainValue | string | 좌석 상한. PERSEAT에만 포함 |
currentSeatNum | integer | 활성 계정 수. PERSEAT에만 포함 |
availableSeatNum | integer | 잔여 좌석 수. PERSEAT에만 포함 |
위 필드만 사용합니다. 응답에는 이 계약에 포함되지 않는 내부 값이 함께 담길 수 있습니다.
라이선스가 등록되지 않은 tenant는 6998과 함께 HTTP 404를 반환합니다.
라이선스 상태 조회
GET /admins/get/license/status는 state, days, spents, expiresOn, paidWhiteLabel을 반환합니다.
라이선스에 주의가 필요하면 같은 HTTP 200 응답에 code와 resultMessage를 덧붙입니다. HTTP 오류가 아니라 성공
응답 안에 담긴 경고 신호입니다.
| 조건 | code | resultMessage |
|---|---|---|
| 만료까지 10일 이내 | 6994 | LICENSE_UNDER_LIMIT |
| 이미 만료됨 | 6995 | LICENSE_FILE_EXPIRATION |
| 좌석 상한 초과. 위 두 조건보다 우선 적용 | 6993 | LICENSE_EXCEED_LIMIT |
| 정상 | 없음 | 없음 |
좌석 상한을 초과한 경우 응답에 currentSeatNum, constrainValue, 음수일 수 있는 availableSeatNum이 함께
담기며 state는 false로 덮어써집니다.
로그인 설정
tenant에서 사용자가 어떻게 인증할지 정합니다.
GET /api/external/v1/admins/login-settings
PATCH /api/external/v1/admins/login-settings
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
loginType | enum | Yes | local, oidc, jwt |
providers | array | No | 인증 공급자 목록. local이면 생략하거나 null |
jwt 설정은 공급자를 정확히 하나 받습니다. oidc 설정은 여러 개를 둘 수 있지만 ACTIVE는 하나여야 합니다.
각 공급자는 수정 시의 ssoProviderSeq, displayName, status, 그리고 type이 loginType과 같아야 하는
config 객체를 담습니다. 값이 다르면 SSO_PROTOCOL_002, 지원하지 않는 프로토콜이면 SSO_PROTOCOL_001을
반환합니다.
oidc의 config는 issuerUrl, clientId, clientSecret을 받습니다. jwt의 config는 issuer, 선택적인
audience, 그리고 public_key 또는 jwks인 keySourceType을 받습니다. 앞은 publicKey, 뒤는 jwksUri를
함께 보냅니다. emailClaimName은 이메일을 읽을 대체 claim 이름이고, errorRedirectUrl은 로그인 실패 시
이동할 위치입니다.
조회 응답은 콜백 주소인 redirectUri와, 슈퍼 관리자가 이 설정을 전체 tenant에 적용 중이면 true인
superAdminEnforced를 함께 반환합니다.
GET /admins/login-settings는 clientSecret과 publicKey를 저장된 그대로 마스킹 없이 포함합니다. 응답을
민감 정보로 취급해 로그에 남기거나 브라우저에 캐시하거나 클라이언트 애플리케이션에 전달하지 않습니다.
브랜딩
GET /api/external/v1/admins/branding
PUT /api/external/v1/admins/branding
브랜딩은 API Key의 tenant에 적용되며 경로에 식별자가 없습니다. 수정은 multipart/form-data로 보냅니다.
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
tabTitle | string | Yes | 브라우저 탭 제목, 2~30자 |
serviceName | string | Yes | 서비스명, 2~30자 |
showPoweredBy | boolean | Yes | 제공자 표기 노출 여부 |
useDefault | boolean | Yes | 기본 이미지를 쓰려면 true, 4개를 직접 등록하려면 false |
favicon | file | 조건부 | ICO 또는 PNG, 최대 500KB. useDefault가 false면 필수 |
logoIcon | file | 조건부 | PNG 또는 SVG, 최대 1MB. useDefault가 false면 필수 |
logoImage | file | 조건부 | PNG 또는 SVG, 최대 2MB. useDefault가 false면 필수 |
emailLogo | file | 조건부 | PNG 또는 SVG, 최대 2MB. useDefault가 false면 필수 |
useDefault가 true면 이미지 필드 4개는 검증 없이 무시됩니다. false인 경우에만 4개 모두 필수이며, 더 적게
보내면 REQUEST_001을 반환합니다.
GET /api/external/v1/admins/branding/images/{type}
type은 favicon, logo-icon, logo-image, email-logo이고, 필수인 source는 custom 또는 default입니다.
라이선스가 없는 tenant는 source와 무관하게 항상 기본 이미지를 받습니다. 따라서 source=custom은 화이트라벨
tenant에서만 의미가 있습니다. 등록된 이미지가 없으면 BRANDING_001을 반환합니다.
접근 제한
사용자가 어디에서 로그인할 수 있는지를 제한합니다.
PUT /api/external/v1/admins/access-restriction/countries
PUT /api/external/v1/admins/access-restriction/ips
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
countries | array | Yes | 허용할 ISO alpha-2 국가 코드 목록 |
ips | array | Yes | 허용할 IPv4 주소 또는 CIDR 목록 |
CIDR의 호스트 비트는 0이어야 하며 IPv6는 지원하지 않습니다. 국가 코드가 잘못되면 ACCESS_002, 주소가 잘못되면
ACCESS_004를 반환합니다.
저장된 값에 덧붙이지 않습니다. 빈 배열을 보내면 모든 항목이 삭제됩니다. 현재 목록을 읽고 수정한 뒤 완성된 결과를 보냅니다.
제한의 켜고 끄기는 system-config/access-restriction-status에서 합니다. 등록된 국가와
주소가 하나도 없는 상태에서 켜면 ACCESS_003을 반환합니다.
공유 설정
GET /api/external/v1/admins/share-settings
PATCH /api/external/v1/admins/share-settings
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
se | boolean | Yes | 공유 기능 사용 여부 |
esa | boolean | 조건부 | 조직 외부 공유 허용. se가 true면 필수 |
sua | boolean | 조건부 | SPECIFIC_USERS 공유 유형 허용. se가 true면 필수 |
ola | boolean | 조건부 | ORG_LINK 공유 유형 허용. se가 true면 필수 |
pa | boolean | 조건부 | PUBLIC_LINK 공유 유형 허용. se가 true면 필수 |
se가 true이면 sua, ola, pa 중 하나 이상도 true여야 합니다. pa를 켜려면 esa도 true여야 합니다.
조회 응답에는 isEnforced가 추가됩니다. true이면 슈퍼 관리자가 모든 tenant에 하나의 설정을 적용 중이라는
뜻이며, 반환되는 값은 이 tenant 자신의 설정이 아니라 글로벌 설정입니다.
SMTP
SMTP 설정은 tenant당 하나입니다. smtpConfigSeq를 보내면 기존 설정을 수정하고, 생략하면 새로 만듭니다.
GET /api/external/v1/admins/smtp-config
POST /api/external/v1/admins/smtp-config
POST /api/external/v1/admins/smtp-config/test
| 파라미터 | Type | 필수 | 설명 |
|---|---|---|---|
clientName | string | Yes | 이 설정의 고객사명 |
host | string | Yes | SMTP 서버 주소 |
port | integer | Yes | SMTP 포트 |
encryptionType | enum | Yes | SSL, TLS, NONE |
authType | enum | Yes | IDPW 또는 OAUTH |
username | string | Yes | SMTP 계정 |
encPwd | string | 조건부 | 비밀번호. authType이 IDPW일 때 사용 |
oauthInfo | string | 조건부 | OAuth access token. authType이 OAUTH일 때 사용 |
fromAddress | string | Yes | 발신자 주소 |
testReceiverAddress | string | Yes | 테스트 메일 수신 주소 |
smtpConfigSeq | integer | 조건부 | 수정할 설정. 테스트 endpoint에는 필수 |
실제로는 둘 중 하나가 필요한데도 encPwd와 oauthInfo는 요청 검증에서 강제되지 않습니다. 그래서 실제로는
발송할 수 없는 설정이 저장될 수 있습니다. 테스트 endpoint로 확인합니다. 발송에 실패하면 SMTP_CONFIG_002,
존재하지 않는 설정을 조회하면 SMTP_CONFIG_001을 반환합니다.
GET /admins/smtp-config는 encPwd를 복호화해 반환합니다. 응답을 민감 정보로 취급하고 서버 측에만 둡니다.
authType이 OAUTH이면 oauthInfo가 access token으로, username이 계정으로 그대로 사용됩니다. 서버는 그
토큰이 해당 계정이나 fromAddress로 발급되었는지 확인하지 않고, 만료된 토큰을 갱신하지도 않습니다. 짝이 맞는지
직접 확인하고 토큰을 수동으로 교체할 계획을 세웁니다.
시스템 설정
GET /api/external/v1/admins/system-config/general
PUT /api/external/v1/admins/system-config/general
GET /api/external/v1/admins/system-config/office
PUT /api/external/v1/admins/system-config/office
GET /api/external/v1/admins/system-config/storage
GET /api/external/v1/admins/system-config/intellect
PUT /api/external/v1/admins/system-config/intellect
GET /api/external/v1/admins/system-config/mfa-status
PUT /api/external/v1/admins/system-config/mfa-status
GET /api/external/v1/admins/system-config/file-size-limit
PUT /api/external/v1/admins/system-config/file-size-limit
GET /api/external/v1/admins/system-config/access-restriction-status
PUT /api/external/v1/admins/system-config/access-restriction-status
GET /api/external/v1/admins/system-config/shares/exists
설정을 처음 만드는 PUT은 201을, 기존 설정을 수정하는 PUT은 200을 반환합니다.
일반
clientDomain은 tenant의 클라이언트 도메인이며, 설정되지 않았으면 빈 문자열로 반환됩니다.
활성 tenant가 둘 이상이면 슈퍼 관리자만 clientDomain을 바꿀 수 있고, 일반 관리자는 SYSTEM_CONFIG_008을
받습니다. 베이스 도메인이 등록되어 있으면 값이 그 도메인으로 끝나야 하며, 아니면 BASE_DOMAIN_004로
실패합니다.
오피스
officeDomain과 officeAdapterName이며 수정 시 둘 다 필수입니다. officeDomain은 URL 형식으로 검증됩니다.
스토리지
읽기 전용입니다. CEPH 또는 S3인 storageType과 함께 bucketName, region, endPoint, status를
반환합니다.
응답에 accessKey와 secretKey가 평문으로 포함됩니다. 이 endpoint를 호출할 수 있는 관리자 키는 tenant의 오브젝트
스토리지 자격증명을 읽을 수 있습니다. 접근 가능한 대상을 제한하고 응답을 클라이언트로 전달하지 않습니다.
기능 토글
intellect, mfa-status, access-restriction-status는 각각 enabled boolean 하나를 읽고 씁니다.
intellectStatus나 status 같은 필드는 없으며 enabled를 사용합니다.
access-restriction-status는 allowedCountries와 allowedIps도 함께 반환합니다. enabled를 true로 설정하려면
국가나 주소가 하나 이상 이미 등록되어 있어야 하며, 아니면 ACCESS_003으로 실패합니다.
파일 크기 제한
maxFileUploadSize는 업로드 상한(byte)입니다. 제한이 없으면 null을 보내고, 값을 보낼 때는 양수여야 합니다.
공유 데이터 확인
shares/exists는 tenant에 공유 기록이 하나라도 있는지를 exists boolean 하나로 알려줍니다. 공유 기능을 끄기
전에 기존 공유에 영향이 있는지 확인할 때 사용합니다.
에러
이 endpoint들이 반환하는 코드 전체 목록은 Errors를 참고합니다.