리소스 역할 부여 API (V2)
역할은 리소스에 대한 접근 수준을 정하는 권한 집합입니다. 역할 부여는 리소스, 사용자나 그룹 등의 주체, 역할 ID를 연결합니다. Foundry의 기본 리소스 역할에는 Owner, Editor, Viewer, Discoverer가 있습니다.
List Resource Roles로 부여된 역할을 조회하고 Add Resource Roles와 Remove Resource Roles로 변경합니다. 조회에는 api:filesystem-read, 변경에는 api:filesystem-write OAuth 권한 범위를 사용합니다.
조회와 변경의 주체 형식
| 용도 | ID가 있는 주체 | 사용자 전체 |
|---|---|---|
조회 응답의 ResourceRole | principalWithId: principalId와 principalType이 필수 | everyone |
추가 및 제거 입력의 ResourceRoleIdentifier | principalIdOnly: principalId만 필수 | everyone |
각 형식은 resourceRolePrincipal.type으로 구분합니다. 조회의 principalType은 USER 또는 GROUP입니다. 쓰기 요청은 이 사용자 또는 그룹 유형을 따로 지정하지 않습니다. 두 역할 자료형에는 resourceRolePrincipal과 roleId가 모두 필요합니다.
everyone의 JSON 값은 {"type":"everyone"}이며 플랫폼의 모든 사용자를 가리킵니다. 특정 조직이나 그룹 구성원만 대상으로 하려는 요청과 구분합니다. 역할 부여가 조직과 보안 표지의 접근 요구조건을 없애지는 않습니다.
역할 ID와 상속
roleId에는 표시 이름이 아니라 실제 ID를 사용합니다. 대상 공간의 프로젝트 역할 집합에 없는 ID를 기본 역할이나 역할 부여에서 참조하면 InvalidRoleIds가 발생합니다. 예시 UUID에 특정 기본 역할의 의미를 임의로 부여하지 않습니다.
조회에 상속된 역할을 포함하려면 includeInherited=true를 명시합니다. 응답의 역할 항목은 주체와 역할 ID를 담으며 상속 출처를 나타내는 별도 필드는 없습니다. 리소스 계층과 실제 역할 설정을 함께 확인합니다.
역할을 제거한 뒤에도 다른 역할 부여 경로가 남을 수 있습니다. 주체의 최종 접근 가능 여부를 확인할 때는 상속된 역할과 조직 및 보안 표지 조건을 함께 고려합니다.