Users API

로그인한 계정에 한정된 모든 동작입니다. API Key가 대표하는 프로필, 저장 용량, 비밀번호, 그리고 사용자별 컬렉션인 최근 문서함·중요 문서함·휴지통·알림, 거기에 클라이언트가 화면을 그리는 데 필요한 테넌트 설정까지 다룹니다. 다른 사람의 계정을 관리하려면 Admin을 참고합니다.

Base URL과 scope

/api/external/v1/users
/api/external/v1/recent
/api/external/v1/starred
/api/external/v1/trash
/api/external/v1/notifications
/api/external/v1/config

여기서는 대부분의 쓰기 동작에 읽기 scope면 충분함

api:write가 필요한 것은 휴지통 쓰기 동작뿐입니다. users, notifications, config 아래는 모두 api:read만 가진 키로 호출할 수 있습니다. 비밀번호 변경, 프로필 수정, 알림 읽음 처리도 마찬가지입니다. api:read 키를 읽기 전용으로 취급하지 않습니다.

중요 문서함과 최근 문서함 등록은 api:write가 필요합니다.

내 계정 조회

GET /api/external/v1/users

API Key가 대표하는 계정을 반환합니다.

Field	Type	의미
userSeq	integer	계정 식별자
userId	string	계정 id. 이메일 주소
userName	string	표시 이름
status	enum	계정 상태. 예: ACTIVE
isActive	boolean	계정 사용 가능 여부
roleType	enum	역할. 예: USER
totalQuotaByte	long	저장 용량 한도(byte)
useQuotaByte	long	사용 중인 용량(byte)
userLanguage	string	언어 설정 - ko, en, auto
countryCode	string	국가 번호
phoneNumber	string	전화번호
defaultLandingPage	string	시작 화면 - home 또는 my-drive
profileImageKey	string	프로필 이미지의 스토리지 키. 없으면 null
tenantSeq	integer	계정이 속한 tenant

프로필 수정

PATCH /api/external/v1/users

multipart/form-data로 보냅니다.

파라미터	Type	필수	설명
ul	string	Yes	언어 설정 - ko, en, auto
dlp	string	Yes	시작 화면 - home 또는 my-drive
pn	string	No	전화번호
ct	string	No	국가 번호
pif	file	No	프로필 이미지
dpi	boolean	No	기존 프로필 이미지 삭제 여부
sk	string	No	스토리지 키

Update profile

curl -X PATCH "https://drive.example.com/api/external/v1/users" \
  -H "Authorization: Bearer replace-with-your-api-key" \
  -F "pn=010-1111-2222" \
  -F "ul=ko" \
  -F "dlp=my-drive" \
  -F "ct=82" \
  -F "dpi=false" \
  -F "pif=@profile.png"

이미지 업로드에 실패하면 USER_007, 이미지 삭제에 실패하면 USER_015를 반환합니다.

프로필 이미지

GET /api/external/v1/users/profile-image
GET /api/external/v1/users/{userSeq}/profile-image
GET /api/external/v1/users/anonymous-profile-image

첫 번째는 본인 이미지, 두 번째는 다른 사용자의 이미지, 세 번째는 대체 아바타를 생성합니다. 세 endpoint 모두 JSON이 아니라 이미지를 스트리밍합니다. 이미지가 없으면 USER_008을 반환합니다.

대체 아바타는 1부터 30 사이의 정수 animal과 color를 필수로 받습니다.

범위를 벗어난 값은 서버 오류로 응답됨

서버가 animal과 color를 검증하지 않습니다. 1~30을 벗어난 값은 검증 오류가 아니라 RESPONSE_001과 HTTP 500으로 실패합니다. 호출 전에 값을 범위 안으로 맞춥니다.

계정 id 중복 확인

GET /api/external/v1/users/exists

파라미터	Type	필수	설명
userId	string	Yes	확인할 계정 id

사용 가능한 id면 성공을 반환합니다. 이미 쓰이는 id는 HTTP 409와 USER_004를 반환합니다. 즉 "중복"은 성공 응답의 boolean이 아니라 실패 응답으로 전달됩니다.

사용자 검색

GET /api/external/v1/users/search

파라미터	Type	필수	설명
sk	string	Yes	계정 id와 표시 이름에 대한 검색 키워드

일치하는 계정을 id·이름·상태·tenant와 함께 반환합니다. 특정 공유에 추가할 사용자를 찾으려면 Shares의 공유 사용자 검색을 사용합니다.

저장 용량

GET /api/external/v1/users/quota

totalQuotaByte, useQuotaByte, 그리고 읽지 않은 알림이 있는지를 알려주는 hasUnread를 반환합니다.

비밀번호 변경

PATCH /api/external/v1/users/password

파라미터	Type	필수	설명
currentPwd	string	Yes	현재 비밀번호
newPwd	string	Yes	새 비밀번호

현재 비밀번호가 틀리면 USER_009, 이전 비밀번호와 같으면 USER_010을 반환합니다.

메일을 통한 비밀번호 재설정

재설정 링크를 보내고 사용하는 endpoint가 셋입니다.

POST /api/external/v1/users/password/reset-link/me
POST /api/external/v1/users/password/reset-link
GET  /api/external/v1/users/password/reset-link/verify
POST /api/external/v1/users/password/reset-link/confirm

첫 번째는 API Key 본인 계정으로 재설정 링크를 보내며 파라미터가 없습니다.

두 번째 endpoint는 임의의 계정을 대상으로 함

POST /password/reset-link는 키 본인 계정이 아니라 요청 body의 userId가 지정한 계정으로 재설정 메일을 보냅니다. 키 보유자가 다른 사용자의 비밀번호 재설정 메일을 발송시킬 수 있습니다. 다른 사람의 비밀번호를 의도적으로 재설정하는 경우가 아니면 /reset-link/me를 쓰고, 이 endpoint에 도달할 수 있는 호출자를 제한합니다. 알 수 없는 userId는 USER_005를 반환합니다.

파라미터	Type	필수	설명
userId	string	Yes	재설정 링크를 보낼 계정. POST /password/reset-link의 body
token	string	Yes	재설정 토큰. verify의 query 파라미터이자 confirm의 body 필드
newPwd	string	Yes	새 비밀번호. confirm의 body

verify는 토큰이 아직 쓸 수 있는지 알려줍니다. 인식되지 않는 토큰은 USER_022, 만료된 토큰은 USER_023을 반환합니다.

계정 탈퇴

PATCH /api/external/v1/users/{userSeq}

이 endpoint는 현재 아무 동작도 하지 않음

탈퇴 처리 로직이 비활성화되어 있습니다. 어떤 userSeq로 호출해도 계정 상태를 바꾸지 않고 성공을 반환합니다. 계정 탈퇴에 이 endpoint를 의존하지 말고, 성공 응답을 처리 완료로 해석하지 않습니다.

보안 로그

GET /api/external/v1/users/log

본인 계정의 로그인·로그아웃·비밀번호 변경 이력을 조회합니다.

파라미터	Type	필수	설명
ps	integer	Yes	가져올 항목 수
ci	long	No	cursor - 이전 페이지의 마지막 userLogSeq

각 항목은 activityType, ipAddress, region, registerDate를 담습니다.

최근 문서함

GET  /api/external/v1/recent
POST /api/external/v1/recent

목록은 항상 최근에 다룬 순으로 정렬되며 정렬 파라미터가 없습니다. 등록은 api:write가 필요하고, 리소스를 가리키는 rs와 공유 리소스일 때의 ss를 받습니다.

파라미터	Type	필수	설명
ps	integer	Yes	페이지 크기, 최소 1
rt	enum	No	FILE 또는 FOLDER
ft	enum	No	파일 유형 - document, spreadsheet, presentation, pdf, image, note
oi	string	No	소유자 id, 최대 254자
sd	date	No	수정일 범위 시작. ed를 함께 보내지 않으면 무시
ed	date	No	수정일 범위 종료. sd를 함께 보내지 않으면 무시
ci	long	No	이전 페이지의 cursor id
cv	object	No	이전 페이지의 cursor value
ct	enum	No	이전 페이지의 cursor type

각 항목은 리소스 필드에 더해 recentSeq, isStarred, shareSeq, 그리고 본인 드라이브면 MY, 공유받은 항목이면 SHARE인 resourceLocation을 담습니다.

중요 문서함

GET    /api/external/v1/starred
POST   /api/external/v1/starred
DELETE /api/external/v1/starred/{starredSeq}

중요 표시 등록과 해제는 api:write 필요

등록은 리소스를 가리키는 rs와 공유 리소스일 때의 ss를 받습니다. 해제는 resourceSeq가 아니라 목록의 starredSeq를 받습니다. 해제에 실패하면 STARRED_001을 반환합니다.

목록은 최근 문서함과 같은 필터를 받고, 추가로 name, size, update 정렬을 위한 sb와 so를 받습니다. 기본 정렬은 이름 오름차순입니다.

휴지통

파일이나 폴더를 삭제하면 제거되지 않고 여기로 이동합니다.

GET    /api/external/v1/trash
PATCH  /api/external/v1/trash/files/{resourceSeq}/restore
PATCH  /api/external/v1/trash/folders/{resourceSeq}/restore
DELETE /api/external/v1/trash/files/{resourceSeq}
DELETE /api/external/v1/trash/folders/{resourceSeq}
DELETE /api/external/v1/trash/empty

복원과 완전 삭제는 api:write 필요

목록은 최근 삭제순이 기본이며 ps, rt, ft, ci, cv, ct와 삭제일 범위를 위한 sd·ed, 삭제한 계정을 지정하는 di, 그리고 name·size·register 정렬을 위한 sb·so를 받습니다. 각 항목은 trashSeq와 원래 위치인 parentFolderSeq·parentFolderName, 삭제한 사람을 담습니다.

복원은 body 파라미터 하나를 받습니다.

파라미터	Type	필수	설명
pe	boolean	Yes	원래 부모 폴더가 아직 존재하는지 여부

pe는 검증 없이 그대로 신뢰됨

서버는 pe를 실제 부모 폴더 상태와 대조하지 않습니다. 실제와 다른 값을 보내면 리소스가 잘못된 위치, 즉 원래 부모 폴더나 드라이브 최상위로 복원되면서도 성공으로 응답합니다. 복원 전에 parentFolderSeq의 현재 상태를 읽고 그 값으로 pe를 정합니다.

복원에 실패하면 RESOURCE_009를 반환합니다. 제거할 수 없는 폴더를 완전 삭제하면 TRASH_001, 비우기에 실패하면 TRASH_CLEAN_UP_001을 반환합니다. 완전 삭제와 비우기는 되돌릴 수 없습니다.

알림

GET   /api/external/v1/notifications
GET   /api/external/v1/notifications/unread-count
PATCH /api/external/v1/notifications/read-all
PATCH /api/external/v1/notifications/{notificationSeq}/read
PATCH /api/external/v1/notifications/{notificationSeq}/unread

5개 모두 API Key 소유자 본인의 알림으로 한정됩니다. 다른 사용자의 notificationSeq를 지정하면 갱신 대상이 없어 NOTIFICATION_002 또는 NOTIFICATION_003으로 실패하며, 존재하지 않는 notificationSeq도 같은 응답입니다.

파라미터	Type	필수	설명
ps	integer	Yes	페이지 크기, 최소 1. 누락되거나 더 작으면 REQUEST_001
ci	long	No	cursor - 이전 응답의 nextCursor
ir	boolean	No	true면 읽은 알림만, false면 읽지 않은 알림만. 생략하면 전체

목록은 항상 notificationSeq 내림차순이므로 cursor가 값 하나이며 nextCursorValue와 nextCursorType은 반환되지 않습니다. 삭제되었거나 비활성인 사용자가 발생시킨 알림은 제외되고, 리소스가 삭제된 경우 resourceType, resourceSeq, resourceName이 null일 수 있습니다.

description의 구조는 actionType에 따라 다릅니다.

actionType	description 필드	의미
SHARED	userName, fileName, tenantSeq, tenantName	리소스가 공유됨
UNSHARED	userName, fileName, tenantSeq, tenantName	공유가 해제됨
FILE_UPLOAD	userName, folderName, fileName	공유 폴더에 업로드가 발생함
STORAGE_WARNING	usagePercentage	저장 용량 경고
STORAGE_EXCEEDED	exceeded	저장 용량 초과

알림 하나를 읽음 또는 읽지 않음으로 바꾸면 그 결과인 unreadCount를 반환합니다. read-all은 처리할 알림이 없어도 성공하며 개수를 반환하지 않습니다.

테넌트 설정

클라이언트가 화면을 올바르게 그리는 데 필요한 읽기 전용 설정입니다. 대상 tenant는 API Key에서 결정되며 요청 host의 tenant와 일치해야 합니다. 일치하지 않으면 REQUEST_006으로 실패합니다.

GET /api/external/v1/config
GET /api/external/v1/config/file-size-limit
GET /api/external/v1/config/office

GET /config는 intellectStatus, shareStatus, tenantCount를 반환합니다. shareStatus는 슈퍼 관리자가 전체 적용 중이면 글로벌 설정값을, 아니면 tenant 설정값을 반영합니다.

GET /config/file-size-limit는 maxFileUploadSize를 byte 단위로 반환합니다. 무제한이거나 한도가 설정되지 않은 경우 이 필드가 아예 생략되고 data가 빈 객체가 됩니다. 값을 비교하지 말고 필드가 있는지로 판단합니다.

GET /config/office는 officeDomain과 officeAdapterName을 반환합니다. 둘 중 하나라도 설정되지 않았으면 일부 데이터를 반환하는 대신 SYSTEM_CONFIG_003으로 실패합니다.

이 endpoint들은 항상 키가 필요함

내부 경로는 공유 링크로 접근한 익명 사용자에게 오피스 설정과 전역 설정 조회를 허용합니다. 여기 문서화된 외부 endpoint는 허용하지 않으며, 항상 유효한 API Key가 필요합니다.

에러

이 endpoint들이 반환하는 코드 전체 목록은 Errors를 참고합니다.