사용자 API

사용자 관리를 위한 API 레퍼런스입니다.

개요

사용자 API는 권한 레벨에 따라 접근 범위가 제한됩니다.

권한 레벨	접근 범위	가능한 작업
Platform Admin (0)	모든 사용자	전체 CRUD
SaaS Admin (1)	SaaS 내 사용자	전체 CRUD
Tenant Admin (2)	Tenant 내 사용자	전체 CRUD
Organization Admin (3)	Organization 내 사용자	조회, 수정
Workspace Admin (4)	Workspace 내 사용자	조회
Team Leader (5)	팀 멤버	조회
Member (6)	본인만	본인 조회/수정

---

엔드포인트

GET /api/v1/users

사용자 목록 조회

Request

GET /api/v1/users?page=1&per_page=15&search=홍길동
Authorization: Bearer YOUR_TOKEN

Query Parameters

파라미터	타입	기본값	설명
page	integer	1	페이지 번호
per_page	integer	15	페이지당 항목 수 (max: 100)
search	string	-	이름/이메일 검색
permission_level	integer	-	권한 레벨 필터
tenant_id	integer	-	테넌트 ID 필터
organization_id	integer	-	조직 ID 필터
workspace_id	integer	-	워크스페이스 ID 필터
sort	string	created_at	정렬 필드
order	string	desc	정렬 방향 (asc/desc)

Response

성공 (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 1,
      "name": "홍길동",
      "email": "hong@example.com",
      "permission_level": 6,
      "permission_level_name": "Member",
      "tenant_id": 1,
      "organization_id": 1,
      "workspace_id": 1,
      "email_verified_at": "2024-01-01T00:00:00Z",
      "created_at": "2024-01-01T00:00:00Z",
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 10,
    "per_page": 15,
    "to": 15,
    "total": 150
  },
  "links": {
    "first": "/api/v1/users?page=1",
    "last": "/api/v1/users?page=10",
    "prev": null,
    "next": "/api/v1/users?page=2"
  }
}

---

GET /api/v1/users/:id

특정 사용자 상세 조회

Request

GET /api/v1/users/1
Authorization: Bearer YOUR_TOKEN

Response

성공 (200 OK)

{
  "success": true,
  "data": {
    "id": 1,
    "name": "홍길동",
    "email": "hong@example.com",
    "permission_level": 6,
    "permission_level_name": "Member",
    "tenant": {
      "id": 1,
      "name": "Example Tenant"
    },
    "organization": {
      "id": 1,
      "name": "Example Org"
    },
    "workspace": {
      "id": 1,
      "name": "Default Workspace"
    },
    "team": {
      "id": 1,
      "name": "Development"
    },
    "email_verified_at": "2024-01-01T00:00:00Z",
    "created_at": "2024-01-01T00:00:00Z",
    "updated_at": "2024-01-01T00:00:00Z"
  }
}

실패 (404 Not Found)

{
  "success": false,
  "message": "사용자를 찾을 수 없습니다."
}

---

POST /api/v1/users

새 사용자 생성

Request

POST /api/v1/users
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "김철수",
  "email": "kim@example.com",
  "password": "SecureP@ss123!",
  "password_confirmation": "SecureP@ss123!",
  "permission_level": 6,
  "tenant_id": 1,
  "organization_id": 1,
  "workspace_id": 1,
  "team_id": 1,
  "send_welcome_email": true
}

Request Body

필드	타입	필수	설명
name	string	✅	이름 (2-100자)
email	string	✅	이메일 (고유)
password	string	✅	비밀번호 (8자 이상, 특수문자 포함)
password_confirmation	string	✅	비밀번호 확인
permission_level	integer	✅	권한 레벨 (0-6)
tenant_id	integer	-	테넌트 ID (Level 1 이상 필수)
organization_id	integer	-	조직 ID (Level 3 이상 필수)
workspace_id	integer	-	워크스페이스 ID (Level 4 이상 필수)
team_id	integer	-	팀 ID (Level 5-6 필수)
send_welcome_email	boolean	-	환영 이메일 발송 (기본: true)

권한 제한

생성자의 권한 레벨보다 높은(숫자가 작은) 레벨의 사용자는 생성할 수 없습니다.

Response

성공 (201 Created)

{
  "success": true,
  "message": "사용자가 생성되었습니다.",
  "data": {
    "id": 2,
    "name": "김철수",
    "email": "kim@example.com",
    "permission_level": 6,
    "created_at": "2024-01-15T00:00:00Z"
  }
}

실패 (422 Unprocessable Entity)

{
  "success": false,
  "message": "입력값을 확인해주세요.",
  "errors": {
    "email": ["이미 사용 중인 이메일입니다."],
    "password": ["비밀번호는 최소 8자 이상이어야 합니다."]
  }
}

---

PUT /api/v1/users/:id

사용자 정보 수정

Request

PUT /api/v1/users/1
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "홍길동 (수정)",
  "email": "hong.new@example.com",
  "permission_level": 5,
  "workspace_id": 2
}

Request Body

필드	타입	설명
name	string	이름
email	string	이메일
password	string	새 비밀번호 (변경 시)
password_confirmation	string	비밀번호 확인
permission_level	integer	권한 레벨
tenant_id	integer	테넌트 ID
organization_id	integer	조직 ID
workspace_id	integer	워크스페이스 ID
team_id	integer	팀 ID

Response

성공 (200 OK)

{
  "success": true,
  "message": "사용자 정보가 수정되었습니다.",
  "data": {
    "id": 1,
    "name": "홍길동 (수정)",
    "email": "hong.new@example.com",
    "updated_at": "2024-01-15T12:00:00Z"
  }
}

---

DELETE /api/v1/users/:id

사용자 삭제 (Soft Delete)

Request

DELETE /api/v1/users/1
Authorization: Bearer YOUR_TOKEN

Response

성공 (200 OK)

{
  "success": true,
  "message": "사용자가 삭제되었습니다."
}

실패 (403 Forbidden)

{
  "success": false,
  "message": "본인 계정은 삭제할 수 없습니다."
}

---

POST /api/v1/users/:id/restore

삭제된 사용자 복원

Request

POST /api/v1/users/1/restore
Authorization: Bearer YOUR_TOKEN

Response

성공 (200 OK)

{
  "success": true,
  "message": "사용자가 복원되었습니다.",
  "data": {
    "id": 1,
    "name": "홍길동",
    "email": "hong@example.com"
  }
}

---

프로필 관리

GET /api/v1/users/me/profile

본인 프로필 상세 조회

GET /api/v1/users/me/profile
Authorization: Bearer YOUR_TOKEN

PUT /api/v1/users/me/profile

본인 프로필 수정

PUT /api/v1/users/me/profile
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "name": "새 이름",
  "avatar": "base64_encoded_image...",
  "timezone": "Asia/Seoul",
  "locale": "ko"
}

PUT /api/v1/users/me/password

본인 비밀번호 변경

PUT /api/v1/users/me/password
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "current_password": "OldP@ss123!",
  "password": "NewP@ss456!",
  "password_confirmation": "NewP@ss456!"
}

---

필터링 예제

특정 테넌트의 관리자만 조회

GET /api/v1/users?tenant_id=1&permission_level=2

이메일로 검색

GET /api/v1/users?search=@example.com

최근 가입순 정렬

GET /api/v1/users?sort=created_at&order=desc

복합 필터

GET /api/v1/users?tenant_id=1&organization_id=5&permission_level=6&search=김&per_page=50

---

오류 코드

HTTP 코드	코드	설명
400	invalid_request	잘못된 요청
401	unauthenticated	인증 필요
403	forbidden	권한 부족
404	not_found	사용자 없음
409	conflict	이메일 중복
422	validation_error	입력값 오류

---

사용 예제

cURL

# 사용자 목록 조회
curl -X GET "https://api.example.com/api/v1/users?page=1&per_page=10" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 사용자 생성
curl -X POST "https://api.example.com/api/v1/users" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "김철수",
    "email": "kim@example.com",
    "password": "SecureP@ss123!",
    "password_confirmation": "SecureP@ss123!",
    "permission_level": 6,
    "tenant_id": 1
  }'

# 사용자 수정
curl -X PUT "https://api.example.com/api/v1/users/1" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name": "홍길동 (수정)"}'

# 사용자 삭제
curl -X DELETE "https://api.example.com/api/v1/users/1" \
  -H "Authorization: Bearer YOUR_TOKEN"

JavaScript

// 사용자 목록 조회 with 필터
const fetchUsers = async (filters = {}) => {
  const params = new URLSearchParams({
    page: 1,
    per_page: 15,
    ...filters,
  });

  const response = await fetch(`/api/v1/users?${params}`, {
    headers: {
      'Authorization': `Bearer ${token}`,
    },
  });

  return response.json();
};

// 사용
const users = await fetchUsers({
  tenant_id: 1,
  search: '홍길동',
});

---

관련 문서

• API 개요 - 공통 응답 형식
• 인증 API - 인증 방법
• 권한 API - 권한 관리
• 테넌트 API - 테넌트 관리
• Permission 모듈 - 권한 시스템 상세