Admin API

하나의 tenant를 관리하는 API입니다. 계정 생성과 관리, 활성화·비활성화, MFA 초기화, 라이선스 관리와 tenant 설정을 다룹니다. 여러 tenant를 관리하려면 Super Admin을 참고하세요. tenant의 감사 기록은 Audit logs에서 설명합니다.

Base URL과 권한

/api/external/v1/admins

이 endpoint를 호출하려면 ADMIN 역할의 계정으로 발급된 API Key가 필요합니다. 슈퍼 관리자의 키로도 호출할 수 있습니다. 예외인 endpoint 두 개는 해당 항목에 표시했습니다.

scope를 검사하지 않음

/admins/**의 접근 권한은 역할로만 결정됩니다. API Key의 scope는 검사하지 않으므로 api:read만 부여된 키로도 계정 생성, 용량 변경, 사용자 비활성화, CSV 가져오기, 라이선스 등록을 할 수 있습니다. 관리자 키는 발급할 때 지정한 scope와 관계없이 모든 권한을 가진 키로 관리하세요.

계정 생성 endpoint로는 관리자 계정을 만들 수 없음

API Key로 인증한 POST /admins는 rt가 USER인 계정만 생성할 수 있습니다. ADMIN을 요청하면 USER_013으로 거부됩니다. 단, 계정 일괄 등록·수정에는 이 제한이 없으므로 해당 항목의 경고를 참고하세요.

모든 기능은 호출한 계정이 속한 tenant 안에서만 동작합니다. userSeq를 받는 endpoint에 다른 tenant의 userSeq를 지정하면 존재하지 않는 계정과 마찬가지로 USER_005를 반환하므로, 다른 tenant의 계정 존재 여부는 알 수 없습니다.

페이지네이션

관리자 API의 목록 조회는 cursor 페이지네이션을 사용합니다. ps로 페이지 크기를, ci로 이전 페이지의 마지막 userSeq를 보냅니다. 값이 없으면 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	역할. API Key로 호출하면 USER만 보낼 수 있음
pif	file	No	프로필 이미지
ct	string	No	국가 번호. 앞의 + 기호 제외, 최대 4자
pn	string	No	전화번호. 구분 기호 제외, 최대 20자

ct와 pn은 함께 보내거나 둘 다 생략해야 합니다. 하나만 보내면 USER_027을 반환합니다.

Create account

curl -X POST "https://drive.example.com/api/external/v1/admins" \
  -H "Authorization: Bearer replace-with-your-TENANTADMIN-API-KEY" \
  -F "ui=user1@example.com" \
  -F "encPwd=User1234!" \
  -F "un=First user" \
  -F "tq=1000000000" \
  -F "rt=USER"

성공하면 새 계정의 userSeq를 반환합니다. 이메일 형식이 잘못되면 USER_002를, 계정 id가 중복되면 USER_004를 반환합니다. 라이선스 사용자 수나 tenant의 가용 용량을 초과하면 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

대상 계정의 다중 인증(MFA) 설정을 해제해 사용자가 다시 등록할 수 있게 합니다. 이 작업은 감사 로그에 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를 반환합니다.

일부 행이 실패하면 JSON 대신 CSV를 반환함

계정 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가 부여된 키로 호출할 수 있습니다.

tenant 범위를 제한하지 않음

이 페이지의 다른 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	휴지통 항목이 차지하는 용량

휴지통을 비우거나 버전 이력을 삭제하면 versionUsedBytes와 trashUsedBytes만큼의 용량을 확보할 수 있습니다.

계정 보안 로그 조회

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를 반환합니다.

존재하지 않는 id는 오류 없이 제외됨

호출한 계정의 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로 포함
constrainValue	string	허용 사용자 수. PERSEAT에만 포함
currentSeatNum	integer	활성 계정 수. PERSEAT에만 포함
availableSeatNum	integer	추가할 수 있는 사용자 수. PERSEAT에만 포함

위 표의 필드만 사용하세요. 응답에는 이 문서에서 설명하지 않는 내부 값이 포함될 수 있습니다. 라이선스가 등록되지 않은 tenant에서는 6998과 함께 HTTP 404를 반환합니다.

라이선스 상태 조회

GET /admins/get/license/status는 state, days, spents, expiresOn을 반환합니다. 라이선스 확인이 필요한 상태이면 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	인증 provider 목록. local이면 생략하거나 null

jwt는 provider를 정확히 하나만 설정할 수 있습니다. oidc는 provider를 여러 개 설정할 수 있지만 ACTIVE 상태는 하나만 허용합니다. 각 provider에는 수정할 때 사용하는 ssoProviderSeq, displayName, status와 config 객체를 지정합니다. config의 type은 loginType과 같아야 합니다. 값이 다르면 SSO_PROTOCOL_002를, 지원하지 않는 프로토콜이면 SSO_PROTOCOL_001을 반환합니다.

oidc의 config에는 issuerUrl, clientId, clientSecret을 지정합니다. jwt의 config에는 issuer, 선택 항목인 audience와 keySourceType(public_key 또는 jwks)을 지정합니다. keySourceType이 public_key면 publicKey를, jwks면 jwksUri를 함께 보냅니다. emailClaimName은 이메일을 가져올 claim 이름을 기본값 대신 지정할 때 사용하고, errorRedirectUrl은 로그인에 실패했을 때 이동할 주소입니다.

조회 응답에는 콜백 주소인 redirectUri와, 슈퍼 관리자가 이 설정을 모든 tenant에 적용 중이면 true인 superAdminEnforced가 함께 포함됩니다.

조회 응답에 secret이 평문으로 포함됨

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	Powered by 문구 표시 여부
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입니다.

등록된 이미지가 없으면 BRANDING_001을 반환합니다.

접근 제한

사용자가 로그인할 수 있는 국가와 IP 주소를 제한합니다.

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를 반환합니다.

두 endpoint 모두 목록 전체를 교체함

보낸 값이 기존 목록에 추가되지 않고 전체 목록을 대체합니다. 빈 배열을 보내면 모든 항목이 삭제됩니다. 현재 목록을 조회해 수정한 뒤 전체 목록을 보내세요.

접근 제한 사용 여부는 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을 반환합니다.

조회 응답에 SMTP 비밀번호가 평문으로 포함됨

GET /admins/smtp-config는 encPwd를 복호화해 반환합니다. 응답을 민감 정보로 취급하고 서버에서만 사용하세요.

OAuth 인증 발송의 제한 사항

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를 운영하면 도메인 수정이 제한됨

활성 tenant가 둘 이상이면 슈퍼 관리자만 clientDomain을 변경할 수 있으며, 일반 관리자가 요청하면 SYSTEM_CONFIG_008을 반환합니다. 베이스 도메인이 등록되어 있으면 값이 해당 도메인으로 끝나야 하며, 그렇지 않으면 BASE_DOMAIN_004로 실패합니다.

Office

officeDomain과 officeAdapterName을 설정하며, 수정할 때 두 값 모두 필수입니다. officeDomain은 URL 형식인지 검증합니다.

스토리지

조회만 할 수 있습니다. storageType(CEPH 또는 S3)과 함께 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를 참고하세요.