사용자

사용자 계정 관리, 권한, 설정, 프로필

개요

모든 사용자 엔드포인트는 /api/v1/users 아래에 있습니다. 대부분의 쓰기 작업에는 관리자 역할이 필요합니다. 일반 사용자는 자신의 데이터만 접근할 수 있습니다. 사용자 계정, 프로필, 권한, UI 설정을 관리합니다.

기본 URL:

목록 조회 및 검색

GET /api/v1/users/

페이지 나눔 사용자 목록. 관리자 전용.

GETAdmin only

선택적 필터링 및 정렬을 포함한 모든 사용자 목록. 페이지 크기는 30으로 고정됩니다.

쿼리 파라미터

이름	타입	설명
`query`	string	이름 또는 이메일로 필터링
`order_by`	string	정렬 기준 필드
`direction`	string	`asc 또는 desc`
`page`	integer	페이지 번호 (기본값: 1, 페이지 크기: 30)
`group_id`	string	그룹 멤버십으로 필터링

응답 200

json

{
"users": [
  {
    "id": "user-uuid",
    "name": "Jane Smith",
    "email": "jane@example.com",
    "role": "user",
    "profile_image_url": "https://...",
    "created_at": 1700000000
  }
],
"count": 150
}

GET /api/v1/users/all

페이지 나눔 없이 모든 사용자를 반환합니다. 관리자 전용.

GETAdmin only

페이지 나눔 없이 모든 사용자를 가져옵니다.

응답 200

json

{
"users": [...],
"count": 150
}

GET /api/v1/users/search

이름 또는 이메일로 사용자를 검색합니다. @멘션 및 자동완성을 위한 최소 객체를 반환합니다.

GETAuth required

이름 또는 이메일로 사용자를 검색합니다.

쿼리 파라미터

이름	타입	설명
`query`	string	검색 문자열

응답 200

json

{
"users": [
  { "id": "user-uuid", "name": "Jane Smith" }
]
}

GET /api/v1/users/active

현재 Socket.IO 연결이 있는 사용자 ID를 반환합니다.

GETAuth required

현재 연결된 사용자 목록을 가져옵니다.

응답 200

json

{
"user_ids": ["uuid-1", "uuid-2"]
}

권한

GET /api/v1/users/permissions

현재 사용자의 유효 권한 세트를 반환합니다. 역할과 그룹 멤버십에서 해결됩니다.

GETAuth required

현재 사용자의 유효 권한을 가져옵니다.

응답 200

json

{
"workspace": {
  "models": false,
  "knowledge": false,
  "prompts": false,
  "tools": false
},
"sharing": {
  "public_models": true,
  "public_knowledge": true,
  "public_tools": true
},
"chat": {
  "file_upload": true,
  "delete": true,
  "share": true,
  "export": true
},
"features": {
  "web_search": true,
  "image_generation": true,
  "code_interpreter": true
}
}

GET /api/v1/users/default/permissions

시스템 전체 기본 권한을 반환합니다. 관리자 전용.

GETAdmin only

시스템 전체 기본 권한을 가져옵니다.

응답 200

json

{
"workspace": { ... },
"sharing": { ... },
"chat": { ... },
"features": { ... }
}

POST /api/v1/users/default/permissions

시스템 전체 기본 권한을 업데이트합니다. 관리자 전용. 전체 권한 객체를 전송하세요.

POSTAdmin only

모든 사용자의 기본 권한을 업데이트합니다.

요청 본문

json

{
"workspace": { ... },
"sharing": { ... },
"chat": { ... },
"features": { ... }
}

응답 200

업데이트된 권한 객체.

사용자 설정

GET /api/v1/users/user/settings

현재 사용자의 저장된 UI 설정(테마, 사이드바 상태, 언어 등)을 반환합니다.

GETAuth required

현재 사용자의 UI 설정을 가져옵니다.

응답 200

json

{
"theme": "light",
"language": "en",
"sidebar": { "collapsed": false }
}

POST /api/v1/users/user/settings/update

현재 사용자의 전체 UI 설정 객체를 저장합니다. 전체 설정 페이로드를 전송하세요.

POSTAuth required

현재 사용자의 UI 설정을 업데이트합니다.

요청 본문

json

{
"theme": "dark",
"language": "en",
"sidebar": { "collapsed": false }
}

응답 200

업데이트된 설정 객체.

사용자 정보 및 프로필

GET /api/v1/users/user/info

현재 사용자의 info 딕셔너리(임의 키-값 메타데이터)를 반환합니다.

GETAuth required

현재 사용자의 커스텀 info 딕셔너리를 가져옵니다.

응답 200

json

{
"logo_url": "https://...",
"custom_field": "value"
}

POST /api/v1/users/user/info/update

현재 사용자의 info 딕셔너리를 병합 업데이트합니다. 제공된 키만 덮어씁니다.

POSTAuth required

현재 사용자의 커스텀 info를 병합 업데이트합니다.

요청 본문

json

{
"logo_url": "https://example.com/logo.png"
}

응답 200

업데이트된 info 딕셔너리.

POST /api/v1/users/user/profile/image

프로필 이미지를 업로드합니다. 파일은 백엔드 스토리지에 저장됩니다.

POSTAuth required

현재 사용자의 프로필 이미지를 업로드합니다.

요청

헤더: Content-Type: multipart/form-data

폼 필드: file — 이미지 파일 (MIME 타입이 image/ 로 시작해야 함).

응답 200

json

{
"url": "/api/v1/users/profile/image/profile_<uuid>.png",
"filename": "profile_<uuid>.png",
"storage_path": "..."
}

오류

상태 코드	설명
`400`	파일이 이미지가 아님

GET /api/v1/users/profile/image

스토리지 경로로 프로필 이미지를 제공합니다.

GETAuth required

스토리지 경로로 프로필 이미지를 제공합니다.

쿼리 파라미터

이름	타입	설명
`path`	string	업로드 엔드포인트에서 반환된 스토리지 경로

응답 200

이미지 파일 (바이너리).

DELETE /api/v1/users/profile/image

스토리지 경로로 프로필 이미지를 삭제합니다.

DELETEAuth required

프로필 이미지를 삭제합니다.

쿼리 파라미터

이름	타입	설명
`path`	string	삭제할 스토리지 경로

응답 200

json

{ "success": true }

사용자 관리 (관리자)

GET /api/v1/users/`{user_id}`

임의 사용자의 공개 프로필을 가져옵니다.

GETAuth required

특정 사용자의 공개 프로필을 가져옵니다.

경로 파라미터

이름	타입	설명
`user_id`	string	사용자 UUID 또는 공유 채팅 소유자를 찾기 위한 `shared-{chat_id}`

응답 200

json

{
"name": "Jane Smith",
"profile_image_url": "https://...",
"active": true
}

GET /api/v1/users/`{user_id}`/active

사용자가 현재 활성 Socket.IO 연결을 가지고 있는지 확인합니다.

GETAuth required

사용자가 현재 연결되어 있는지 확인합니다.

응답 200

json

{ "active": true }

GET /api/v1/users/groups

현재 사용자가 속한 그룹을 가져옵니다.

GETAuth required

현재 사용자의 그룹을 가져옵니다.

응답 200

json

[
{
  "id": "group-uuid",
  "name": "Engineering",
  "description": "Engineering team",
  "user_ids": ["user-uuid-1", "user-uuid-2"],
  "created_at": 1700000000
}
]

POST /api/v1/users/`{user_id}`/update

임의 사용자의 계정 필드를 업데이트합니다. 해당 사용자 자신이 아닌 경우 기본 관리자를 수정할 수 없습니다. 관리자 전용.

POSTAdmin only

임의 사용자의 계정을 업데이트합니다. 관리자 전용.

경로 파라미터

이름	타입	설명
`user_id`	string	사용자 UUID

요청 본문

json

{
"name": "New Name",
"email": "new@example.com",
"role": "user",
"profile_image_url": "https://...",
"password": "new-password",
"info": { "logo_url": "..." }
}

참고: password 는 선택 사항입니다. info 는 기존 info와 병합됩니다.

응답 200

업데이트된 사용자 객체.

오류

상태 코드	설명
`403`	기본 관리자를 수정할 수 없거나 권한 부족

DELETE /api/v1/users/`{user_id}`

사용자를 영구적으로 삭제합니다. 기본 관리자 또는 자신은 삭제할 수 없습니다. 관리자 전용.

DELETEAdmin only

사용자를 영구적으로 삭제합니다.

경로 파라미터

이름	타입	설명
`user_id`	string	사용자 UUID

응답 200

json

true

오류

상태 코드	설명
`403`	기본 관리자 또는 자신은 삭제 불가
`404`	사용자를 찾을 수 없음

사용자

개요

목록 조회 및 검색

GET /api/v1/users/

GET /api/v1/users/all

GET /api/v1/users/search

GET /api/v1/users/active

권한

GET /api/v1/users/permissions

GET /api/v1/users/default/permissions

POST /api/v1/users/default/permissions

사용자 설정

GET /api/v1/users/user/settings

POST /api/v1/users/user/settings/update

사용자 정보 및 프로필

GET /api/v1/users/user/info

POST /api/v1/users/user/info/update

POST /api/v1/users/user/profile/image

GET /api/v1/users/profile/image

DELETE /api/v1/users/profile/image

사용자 관리 (관리자)

GET /api/v1/users/{user_id}

GET /api/v1/users/{user_id}/active

GET /api/v1/users/groups

POST /api/v1/users/{user_id}/update

DELETE /api/v1/users/{user_id}

GET /api/v1/users/`{user_id}`

GET /api/v1/users/`{user_id}`/active

POST /api/v1/users/`{user_id}`/update

DELETE /api/v1/users/`{user_id}`