> For the complete documentation index, see [llms.txt](https://docs.archisketch.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.archisketch.com/guide/dev-kr/api-sdk/api/undefined-1.md).
# 사용자
## 사용자 정보 수정
> 사용자의 이름 또는 역할을 수정합니다.\
> \
> \### 사용처\
> \- 사용자 이름 변경\
> \- 사용자 역할 변경\
> \
> \### 제약 조건\
> \- name과 role 중 하나 이상 필수\
> \- name: 1\~100자 (null이면 변경하지 않음)\
> \- role: USER, DESIGNER, MANAGER, ADMIN 중 선택 (null이면 변경하지 않음)
```json
{"openapi":"3.1.0","info":{"title":"Open API","version":"snapshot"},"tags":[{"name":"사용자"}],"servers":[{"url":"https://openapi.archisketch.com"}],"security":[{"open-api-key":[]}],"components":{"securitySchemes":{"open-api-key":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"UpdateUserRequest":{"type":"object","properties":{"name":{"type":"string","description":"변경할 이름 (null이면 변경하지 않음)"},"role":{"type":"string","description":"변경할 역할 (null이면 변경하지 않음)","enum":["USER","DESIGNER","MANAGER","ADMIN"]}}},"ApiResponseUnit":{"type":"object","properties":{"result":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"data":{"description":"응답 데이터"},"error":{"$ref":"#/components/schemas/ErrorMessage","description":"에러 응답, result FAIL 시 제공"}},"required":["result"]},"ErrorMessage":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INTERNAL_ERROR","BAD_REQUEST","NOT_FOUND","CONFLICT","FORBIDDEN"]},"message":{"type":"string","description":"에러 메시지"}}}}},"paths":{"/api/v1/users/{id}":{"put":{"tags":["사용자"],"summary":"사용자 정보 수정","description":"사용자의 이름 또는 역할을 수정합니다.\n\n### 사용처\n- 사용자 이름 변경\n- 사용자 역할 변경\n\n### 제약 조건\n- name과 role 중 하나 이상 필수\n- name: 1~100자 (null이면 변경하지 않음)\n- role: USER, DESIGNER, MANAGER, ADMIN 중 선택 (null이면 변경하지 않음)\n","operationId":"updateUser","parameters":[{"name":"id","in":"path","description":"사용자 ID","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"수정할 사용자 정보","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseUnit"}}}}}}}}}
```
## 사용자 상태 변경
> 사용자의 활성화 상태를 변경합니다.\
> \
> \### 사용처\
> \- 사용자 계정 활성화 (ACTIVE)\
> \- 사용자 계정 비활성화 (DELETE)\
> \
> \### 상태 값\
> \- ACTIVE: 사용자를 활성화합니다.\
> \- DELETE: 사용자를 비활성화합니다.
```json
{"openapi":"3.1.0","info":{"title":"Open API","version":"snapshot"},"tags":[{"name":"사용자"}],"servers":[{"url":"https://openapi.archisketch.com"}],"security":[{"open-api-key":[]}],"components":{"securitySchemes":{"open-api-key":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"UpdateUserStatusRequest":{"type":"object","properties":{"status":{"type":"string","description":"변경할 상태 (ACTIVE: 활성화, DELETE: 비활성화)","enum":["ACTIVE","DELETE"]}},"required":["status"]},"ApiResponseUnit":{"type":"object","properties":{"result":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"data":{"description":"응답 데이터"},"error":{"$ref":"#/components/schemas/ErrorMessage","description":"에러 응답, result FAIL 시 제공"}},"required":["result"]},"ErrorMessage":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INTERNAL_ERROR","BAD_REQUEST","NOT_FOUND","CONFLICT","FORBIDDEN"]},"message":{"type":"string","description":"에러 메시지"}}}}},"paths":{"/api/v1/users/{id}":{"patch":{"tags":["사용자"],"summary":"사용자 상태 변경","description":"사용자의 활성화 상태를 변경합니다.\n\n### 사용처\n- 사용자 계정 활성화 (ACTIVE)\n- 사용자 계정 비활성화 (DELETE)\n\n### 상태 값\n- ACTIVE: 사용자를 활성화합니다.\n- DELETE: 사용자를 비활성화합니다.\n","operationId":"changeUserStatus","parameters":[{"name":"id","in":"path","description":"사용자 ID","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"변경할 상태","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserStatusRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseUnit"}}}}}}}}}
```
## 사용자 목록 조회
> 사용자 목록을 조회합니다.\
> \
> \### 사용처\
> \- 기업 소속 사용자 목록 조회\
> \- 역할별, 카테고리별 사용자 필터링\
> \- 사용자 검색 및 관리\
> \
> \### 페이지네이션\
> \- offset 기반 페이징 (0부터 시작)\
> \- limit: 페이지 크기 (최소 1, 최대 100)\
> \- 응답의 hasNext로 다음 페이지 존재 여부 확인\
> \
> \### 필터 조건\
> \- email: 이메일 필터\
> \- name: 이름 필터\
> \- roles: 역할 필터 (USER, DESIGNER, MANAGER, ADMIN)\
> \- categoryId: 카테고리 ID 필터\
> \- sortType: 정렬 기준 (기본값: ID\_DESC)
```json
{"openapi":"3.1.0","info":{"title":"Open API","version":"snapshot"},"tags":[{"name":"사용자"}],"servers":[{"url":"https://openapi.archisketch.com"}],"security":[{"open-api-key":[]}],"components":{"securitySchemes":{"open-api-key":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"ApiResponsePageResponseUserResponse":{"type":"object","properties":{"result":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"data":{"$ref":"#/components/schemas/PageResponseUserResponse","description":"응답 데이터"},"error":{"$ref":"#/components/schemas/ErrorMessage","description":"에러 응답, result FAIL 시 제공"}},"required":["result"]},"PageResponseUserResponse":{"type":"object","properties":{"content":{"type":"array","description":"콘텐츠 목록","items":{"$ref":"#/components/schemas/UserResponse"}},"hasNext":{"type":"boolean","description":"다음 페이지 존재 여부"},"totalCount":{"type":"integer","format":"int64","description":"전체 개수"}},"required":["content","hasNext","totalCount"]},"UserResponse":{"type":"object","properties":{"id":{"type":"string","description":"사용자 ID"},"name":{"type":"string","description":"사용자 이름"},"imageUrl":{"type":"string","description":"프로필 이미지 URL"},"email":{"type":"string","description":"이메일"},"role":{"type":"string","description":"역할 (USER: 일반 사용자, DESIGNER: 디자이너, MANAGER: 매니저, ADMIN: 관리자)","enum":["USER","DESIGNER","MANAGER","ADMIN"]},"categoryId":{"type":"string","description":"카테고리 ID"},"activated":{"type":"boolean","description":"활성화 여부"},"lastActiveAt":{"type":"string","format":"date-time","description":"마지막 활동 일시"},"createdAt":{"type":"string","format":"date-time","description":"생성일시"},"updatedAt":{"type":"string","format":"date-time","description":"수정일시"}},"required":["activated","createdAt","email","id","role","updatedAt"]},"ErrorMessage":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INTERNAL_ERROR","BAD_REQUEST","NOT_FOUND","CONFLICT","FORBIDDEN"]},"message":{"type":"string","description":"에러 메시지"}}}}},"paths":{"/api/v1/users":{"get":{"tags":["사용자"],"summary":"사용자 목록 조회","description":"사용자 목록을 조회합니다.\n\n### 사용처\n- 기업 소속 사용자 목록 조회\n- 역할별, 카테고리별 사용자 필터링\n- 사용자 검색 및 관리\n\n### 페이지네이션\n- offset 기반 페이징 (0부터 시작)\n- limit: 페이지 크기 (최소 1, 최대 100)\n- 응답의 hasNext로 다음 페이지 존재 여부 확인\n\n### 필터 조건\n- email: 이메일 필터\n- name: 이름 필터\n- roles: 역할 필터 (USER, DESIGNER, MANAGER, ADMIN)\n- categoryId: 카테고리 ID 필터\n- sortType: 정렬 기준 (기본값: ID_DESC)","operationId":"getUsers","parameters":[{"name":"email","in":"query","description":"이메일","required":false,"schema":{"type":"string"}},{"name":"name","in":"query","description":"이름","required":false,"schema":{"type":"string"}},{"name":"roles","in":"query","description":"역할","required":false,"schema":{"type":"array","items":{"type":"string","description":"사용자 권한","enum":["USER","DESIGNER","MANAGER","ADMIN"]}}},{"name":"categoryId","in":"query","description":"카테고리 ID","required":false,"schema":{"type":"string"}},{"name":"sortType","in":"query","description":"정렬 유형","required":false,"schema":{"type":"string","default":"ID_DESC","description":"정렬 타입","enum":["ID_DESC","ID_ASC","NAME_ASC","NAME_DESC","UPDATED_ASC","UPDATED_DESC"]}},{"name":"offset","in":"query","description":"페이지 번호 (0부터 시작, offset 페이징)","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"limit","in":"query","description":"페이지 크기 (최소: 1, 최대: 100)","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponsePageResponseUserResponse"}}}}}}}}}
```
## 사용자 생성
> 사용자를 생성합니다.\
> \
> \### 사용처\
> \- 새로운 기업 사용자 등록\
> \- 관리자가 사용자 계정 생성\
> \
> \### 제약 조건\
> \- 비밀번호: 8\~128자\
> \- 이름: 1\~100자\
> \- 역할: USER, DESIGNER, MANAGER, ADMIN 중 선택\
> \- 카테고리 ID: 선택 사항
```json
{"openapi":"3.1.0","info":{"title":"Open API","version":"snapshot"},"tags":[{"name":"사용자"}],"servers":[{"url":"https://openapi.archisketch.com"}],"security":[{"open-api-key":[]}],"components":{"securitySchemes":{"open-api-key":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"CreateUserRequest":{"type":"object","properties":{"name":{"type":"string","description":"사용자 이름"},"email":{"type":"string","description":"이메일"},"password":{"type":"string","description":"비밀번호"},"role":{"type":"string","description":"역할","enum":["USER","DESIGNER","MANAGER","ADMIN"]},"categoryId":{"type":"string","description":"카테고리 ID (선택)"}},"required":["email","name","password","role"]},"ApiResponseUnit":{"type":"object","properties":{"result":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"data":{"description":"응답 데이터"},"error":{"$ref":"#/components/schemas/ErrorMessage","description":"에러 응답, result FAIL 시 제공"}},"required":["result"]},"ErrorMessage":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INTERNAL_ERROR","BAD_REQUEST","NOT_FOUND","CONFLICT","FORBIDDEN"]},"message":{"type":"string","description":"에러 메시지"}}}}},"paths":{"/api/v1/users":{"post":{"tags":["사용자"],"summary":"사용자 생성","description":"사용자를 생성합니다.\n\n### 사용처\n- 새로운 기업 사용자 등록\n- 관리자가 사용자 계정 생성\n\n### 제약 조건\n- 비밀번호: 8~128자\n- 이름: 1~100자\n- 역할: USER, DESIGNER, MANAGER, ADMIN 중 선택\n- 카테고리 ID: 선택 사항\n","operationId":"createUser","requestBody":{"description":"사용자 생성 요청","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateUserRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseUnit"}}}}}}}}}
```
## 사용자 비밀번호 변경
> 사용자의 비밀번호를 변경합니다.\
> \
> \### 제약 조건\
> \- 비밀번호: 8\~128자\
> \- 비활성화된 사용자도 변경 가능
```json
{"openapi":"3.1.0","info":{"title":"Open API","version":"snapshot"},"tags":[{"name":"사용자"}],"servers":[{"url":"https://openapi.archisketch.com"}],"security":[{"open-api-key":[]}],"components":{"securitySchemes":{"open-api-key":{"type":"apiKey","name":"x-api-key","in":"header"}},"schemas":{"UpdateUserPasswordRequest":{"type":"object","properties":{"password":{"type":"string","description":"변경할 비밀번호"}},"required":["password"]},"ApiResponseUnit":{"type":"object","properties":{"result":{"type":"string","description":"응답 결과 타입","enum":["SUCCESS","FAIL"]},"data":{"description":"응답 데이터"},"error":{"$ref":"#/components/schemas/ErrorMessage","description":"에러 응답, result FAIL 시 제공"}},"required":["result"]},"ErrorMessage":{"type":"object","properties":{"errorCode":{"type":"string","description":"에러 코드","enum":["INTERNAL_ERROR","BAD_REQUEST","NOT_FOUND","CONFLICT","FORBIDDEN"]},"message":{"type":"string","description":"에러 메시지"}}}}},"paths":{"/api/v1/users/{id}/password":{"patch":{"tags":["사용자"],"summary":"사용자 비밀번호 변경","description":"사용자의 비밀번호를 변경합니다.\n\n### 제약 조건\n- 비밀번호: 8~128자\n- 비활성화된 사용자도 변경 가능","operationId":"updateUserPassword","parameters":[{"name":"id","in":"path","description":"사용자 ID","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"변경할 비밀번호","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateUserPasswordRequest"}}},"required":true},"responses":{"200":{"description":"모든 응답은 200으로 내려갑니다 (성공 실패 포함) (장애상황에서만 5xx 노출)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiResponseUnit"}}}}}}}}}
```