권한 API

역할 및 권한 관리를 위한 API 레퍼런스입니다.

개요

Multi-SaaS Kit은 권한 시스템 (Level 0~6, ADR-058)을 사용합니다.

Level	명칭	설명
0	Platform Admin	전체 플랫폼 관리
1	SaaS Admin	SaaS 인스턴스 관리
2	Tenant Admin	테넌트 관리
3	Organization Admin	조직 관리
4	Workspace Admin	워크스페이스 관리
5	Team Leader	팀 관리
6	Member	일반 멤버

---

엔드포인트

GET /api/v1/permissions/levels

사용 가능한 권한 레벨 목록 조회

Request

GET /api/v1/permissions/levels
Authorization: Bearer YOUR_TOKEN

Response

성공 (200 OK)

{
  "success": true,
  "data": [
    {
      "level": 0,
      "name": "Platform Admin",
      "name_ko": "플랫폼 관리자",
      "description": "전체 플랫폼을 관리합니다.",
      "scope": "platform",
      "can_create_below": true
    },
    {
      "level": 1,
      "name": "SaaS Admin",
      "name_ko": "SaaS 관리자",
      "description": "SaaS 인스턴스를 관리합니다.",
      "scope": "saas",
      "can_create_below": true
    },
    {
      "level": 2,
      "name": "Tenant Admin",
      "name_ko": "테넌트 관리자",
      "description": "테넌트를 관리합니다.",
      "scope": "tenant",
      "can_create_below": true
    },
    {
      "level": 3,
      "name": "Organization Admin",
      "name_ko": "조직 관리자",
      "description": "조직을 관리합니다.",
      "scope": "organization",
      "can_create_below": true
    },
    {
      "level": 4,
      "name": "Workspace Admin",
      "name_ko": "워크스페이스 관리자",
      "description": "워크스페이스를 관리합니다.",
      "scope": "workspace",
      "can_create_below": true
    },
    {
      "level": 5,
      "name": "Team Leader",
      "name_ko": "팀 리더",
      "description": "팀을 관리합니다.",
      "scope": "team",
      "can_create_below": true
    },
    {
      "level": 6,
      "name": "Member",
      "name_ko": "멤버",
      "description": "일반 멤버입니다.",
      "scope": "personal",
      "can_create_below": false
    }
  ]
}

---

GET /api/v1/permissions/my

현재 사용자의 권한 정보 조회

Request

GET /api/v1/permissions/my
Authorization: Bearer YOUR_TOKEN

Response

성공 (200 OK)

{
  "success": true,
  "data": {
    "permission_level": 2,
    "permission_level_name": "Tenant Admin",
    "scope": {
      "type": "tenant",
      "tenant_id": 1,
      "tenant_name": "Example Company"
    },
    "abilities": [
      "tenant:read",
      "tenant:write",
      "organization:read",
      "organization:write",
      "organization:create",
      "user:read",
      "user:write",
      "user:create",
      "user:delete"
    ],
    "restrictions": {
      "cannot_access_other_tenants": true,
      "cannot_modify_higher_level_users": true
    }
  }
}

---

PUT /api/v1/users/:id/permission

사용자 권한 레벨 변경

권한 제한

• 본인의 권한은 변경할 수 없습니다.
• 자신보다 높은 권한(숫자가 작은)으로 변경할 수 없습니다.
• 자신보다 높은 권한의 사용자 권한을 변경할 수 없습니다.

Request

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

{
  "permission_level": 5,
  "scope": {
    "organization_id": 1,
    "workspace_id": 2,
    "team_id": 3
  }
}

Request Body

필드	타입	필수	설명
permission_level	integer	✅	새 권한 레벨 (0-6)
scope	object	-	권한 범위 (레벨에 따라 필요)
scope.tenant_id	integer	-	Level 2+ 필요
scope.organization_id	integer	-	Level 3+ 필요
scope.workspace_id	integer	-	Level 4+ 필요
scope.team_id	integer	-	Level 5-6 필요

Response

성공 (200 OK)

{
  "success": true,
  "message": "사용자 권한이 변경되었습니다.",
  "data": {
    "user_id": 5,
    "old_permission_level": 6,
    "new_permission_level": 5,
    "changed_by": {
      "id": 1,
      "name": "관리자"
    },
    "changed_at": "2024-01-20T12:00:00Z"
  }
}

실패 (403 Forbidden)

{
  "success": false,
  "message": "권한이 부족합니다.",
  "errors": {
    "permission_level": ["자신보다 높은 권한으로 변경할 수 없습니다."]
  }
}

---

권한 검사 API

POST /api/v1/permissions/check

특정 작업에 대한 권한 검사

Request

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

{
  "action": "user:create",
  "resource": {
    "type": "user",
    "tenant_id": 1,
    "permission_level": 6
  }
}

Response

성공 (200 OK)

{
  "success": true,
  "data": {
    "allowed": true,
    "reason": null
  }
}

{
  "success": true,
  "data": {
    "allowed": false,
    "reason": "생성하려는 사용자의 권한 레벨이 본인보다 높습니다."
  }
}

---

GET /api/v1/permissions/abilities

현재 사용자가 수행 가능한 작업 목록

Request

GET /api/v1/permissions/abilities
Authorization: Bearer YOUR_TOKEN

Response

성공 (200 OK)

{
  "success": true,
  "data": {
    "tenant": {
      "read": true,
      "write": true,
      "delete": false
    },
    "organization": {
      "read": true,
      "write": true,
      "create": true,
      "delete": true
    },
    "workspace": {
      "read": true,
      "write": true,
      "create": true,
      "delete": true
    },
    "team": {
      "read": true,
      "write": true,
      "create": true,
      "delete": true
    },
    "user": {
      "read": true,
      "write": true,
      "create": true,
      "delete": true,
      "max_creatable_level": 3
    }
  }
}

---

권한 로그

GET /api/v1/permissions/logs

권한 변경 이력 조회

Request

GET /api/v1/permissions/logs?page=1&user_id=5
Authorization: Bearer YOUR_TOKEN

Query Parameters

파라미터	타입	설명
user_id	integer	특정 사용자 필터
action	string	작업 유형 (grant/revoke/change)
from_date	date	시작 날짜
to_date	date	종료 날짜

Response

성공 (200 OK)

{
  "success": true,
  "data": [
    {
      "id": 100,
      "user_id": 5,
      "user_name": "홍길동",
      "action": "change",
      "old_permission_level": 6,
      "new_permission_level": 5,
      "changed_by": {
        "id": 1,
        "name": "관리자"
      },
      "reason": "팀 리더로 승격",
      "ip_address": "192.168.1.100",
      "created_at": "2024-01-20T12:00:00Z"
    }
  ],
  "meta": {
    "total": 25
  }
}

---

권한 상속 규칙

상위 권한 포함

상위 레벨(숫자가 작은)은 하위 레벨의 모든 권한을 포함합니다.

Level 0 (Platform Admin)
  └── Level 1 (SaaS Admin)
        └── Level 2 (Tenant Admin)
              └── Level 3 (Organization Admin)
                    └── Level 4 (Workspace Admin)
                          └── Level 5 (Team Leader)
                                └── Level 6 (Member)

범위 제한

레벨	접근 가능 범위
0-1	모든 테넌트
2	자기 테넌트 내 모든 데이터
3	자기 조직 내 모든 데이터
4	자기 워크스페이스 내 모든 데이터
5	자기 팀 내 모든 데이터
6	자기 데이터만

---

오류 코드

HTTP 코드	코드	설명
400	invalid_level	잘못된 권한 레벨
403	forbidden	권한 부족
403	cannot_escalate	권한 상승 불가
403	cannot_modify_self	본인 권한 변경 불가
404	user_not_found	사용자 없음
422	invalid_scope	잘못된 범위 설정

---

사용 예제

cURL

# 내 권한 조회
curl -X GET "https://api.example.com/api/v1/permissions/my" \
  -H "Authorization: Bearer YOUR_TOKEN"

# 사용자 권한 변경
curl -X PUT "https://api.example.com/api/v1/users/5/permission" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "permission_level": 5,
    "scope": {
      "organization_id": 1,
      "team_id": 3
    }
  }'

# 권한 검사
curl -X POST "https://api.example.com/api/v1/permissions/check" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "action": "user:delete",
    "resource": {
      "type": "user",
      "id": 10
    }
  }'

JavaScript

// 권한 레벨 변경
const changePermission = async (userId, newLevel, scope = {}) => {
  const response = await fetch(`/api/v1/users/${userId}/permission`, {
    method: 'PUT',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      permission_level: newLevel,
      scope,
    }),
  });

  return response.json();
};

// 사용
await changePermission(5, 5, {
  organization_id: 1,
  team_id: 3,
});

---

관련 문서

• API 개요 - 공통 응답 형식
• 사용자 API - 사용자 관리
• Permission 모듈 - 권한 시스템 상세
• 권한 시스템 - 개념 설명