> This page is for 플랫폼, version 레거시. > For other versions, use one of these documentation indexes: > - V4 (default): https://next.developer.frame.io/platform/v4/llms.txt > - V4 실험적: https://next.developer.frame.io/platform/v4-experimental/llms.txt > - 레거시: https://next.developer.frame.io/platform/v2/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://next.developer.frame.io/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://next.developer.frame.io/_mcp/server. # 사용자 관리 ## 개요 이 튜토리얼은 Frame.io API를 통한 기본적인 사용자 관리 방법을 다룹니다. 이 가이드는 독자가 이미 OAuth 2.0 또는 개발자 토큰을 통한 [인증](/getting-started/authentication) 설정을 완료했다고 가정합니다. ### 핵심 개념 서로 다른 팀 멤버 역할과 권한에 대한 구체적인 차이를 차치하더라도, Frame.io API를 통해 사용자를 관리할 때 반드시 이해해야 할 두 가지 핵심 사항이 있습니다. 1. **팀 멤버는 팀에 속하며**, 해당 팀 내의 모든 비공개 프로젝트에 액세스할 수 있습니다. 팀 관리자와 관리자 모두 팀 멤버 역할의 확장 형태입니다. 2. **프로젝트 협업자는 단일 프로젝트에 속합니다**. 이러한 프로젝트의 구성 방식에 따라 프레젠테이션을 생성하거나, 에셋을 다운로드하거나, 다른 협업자를 초대할 수 있는 권한이 제한될 수 있습니다. 자세한 내용은 [팀 멤버 대 협업자](https://support.frame.io/getting-started/sharing-with-your-team-or-clients/difference-between-team-members-vs-collaborators) 및 [계정 관리 역할](https://support.frame.io/enterprise-accounts/enterprise-account-management-roles)에 대한 저희 지원 문서를 참조하세요. ### 사용자가 계정에 참여하는 방식 일반적으로 새 사용자는 기존 사용자가 직접 초대하거나, 고유한 프로젝트 참여 URL을 통해 초대받습니다. 팀 멤버는 다음과 같은 작업도 수행할 수 있습니다. 1. 계정 내 공개 팀에 속한 비공개 프로젝트에 본인을 스스로 추가 2. 계정 내 공개 팀에 본인을 스스로 추가 3. 계정 내 비공개 팀에 참여 요청 모든 경우에 참여 활동은 기존 소속 여부 확인, "대기 중" 기록 생성, 필요한 경우 초대장이나 참여 요청 이메일 발송 등 일련의 논리적인 단계를 거치게 됩니다. 다행인 점은 이 모든 로직이 Frame.io API에 의해 추상화되어 있다는 것입니다. 프로젝트에 누군가를 추가하려면 협업자 경로를 사용하고, 팀에 초대하려면 팀 구성원 경로를 사용하면 됩니다. ### 필수 범위 | 범위 | 이유 | | ---------- | ---------- | | **Teams:** Update | 팀 멤버를 추가 및 제거합니다. | | **Projects:** Update | 프로젝트 협업자를 추가 및 제거합니다. | ## 팀 멤버 관리 ### 팀원 추가 팀에 새 팀 구성원을 추가하려면 다음이 필요합니다. 1. 타깃 팀의 `id` 2. 타깃 사용자의 이메일 주소. 여기에서 다음과 같이 본문 페이로드에 타깃 사용자의 이메일을 포함하여 `https://api.frame.io/v2/teams/:id/members`로 인증된 `POST` 요청을 보내기만 하면 됩니다. ```json { "email": "user@example.com" } ``` **초대한 사용자가 이미 귀하 조직의 팀 구성원이라면** API 응답에 해당 내용이 표시됩니다. ```json { "_type": "team_member", "id": "", "role": "member", "team_id": "", "user_id": "" } ``` **초대한 사용자가 아직 귀하의 조직에 없다면** 요청 시 초대 흐름이 트리거되며, API 응답은 다음과 같은 형태를 띠게 됩니다. ```json { "_type": "pending_team_member", "email": "user@example.com", "id": "", "role": "member", "team_id": " } ``` **참고**: 아직 사용자가 생성되거나 인식되지 않았으므로 `pending_team_member` 응답에는 매핑 가능한 `user_id`가 존재하지 않습니다. ### 팀원 제거 팀에서 팀 구성원을 제거하려면 다음이 필요합니다. 1. 타깃 팀의 `id` 2. 타깃 사용자의 이메일 주소. 여기에서는 팀 구성원을 추가할 때와 동일한 URL로 `DELETE` 호출을 수행하되, 다음과 같이 특수한 쿼리 문자열을 추가하여 전달하게 됩니다. `DELETE`[`https://api.frame.io/v2/teams/:id/members/_?email=user@example.com`](ref:post_teams-teamid-members) `/_?email=` 구조를 **주의 깊게 살펴보세요**. 이는 API 요청 시 추가 데이터(이 경우 사용자의 이메일 주소)를 함께 요청할 수 있게 해 주는 Frame.io API의 'include'라는 특수 패턴입니다. 호출이 성공하면 API는 팀 구성원을 추가할 때와 유사한 페이로드를 반환합니다. 팀 구성원이 처음으로 삭제되는 경우 호출 시간에 맞춰 업데이트된 `updated_at` 속성을 확인할 수 있습니다. 팀 구성원이 이전에 이미 삭제된 적이 있다면 이 타임스탬프는 업데이트되지 않습니다(즉, 팀 구성원이 최초로 제거되었던 시간이 반영됨). ```json { "_type": "team_member", "id": "", "role": "member", "team_id": "", "user_id": "", "updated_at": "" } ``` 존재하지 않거나 해당 팀과 연결된 적이 없는 팀 구성원을 제거하려고 하면 404 오류가 발생합니다. ## 프로젝트 협업자 관리 ### 프로젝트 협업자 추가 협업자 관리는 팀 멤버 관리와 매우 유사합니다. 팀에 새로운 협업자를 추가하려면 다음이 필요합니다. 1. 타깃 프로젝트의 `id` 2. 타깃 사용자의 이메일 주소. 해당 정보를 바탕으로 [`https://api.frame.io/v2/projects/:id/collaborators`](ref:post_projects-projectid-collaborators)로 인증된 `POST` 요청을 보내고, 본문 페이로드에 타깃 사용자의 이메일을 포함시킵니다. ```json { "email": "user@example.com" } ``` **초대한 사용자가 인식되고** 협업자 역할이 즉시 인스턴스화될 수 있다면 API 응답도 이를 반영하며, 전체 User 오브젝트를 반환하게 됩니다. ```json { "_type": "collaborator", "creator_id": "", "id": "", "project_id": "", "user": { "_type": "user", <...> }, "user_id": "" } ``` 사용자가 이미 귀하 조직의 팀 구성원이지만 타깃 프로젝트의 멤버가 아닌 경우, 계속해서 협업자 경로를 사용할 수 있으며 API는 위와 같이 응답합니다. 백그라운드에서 해당 팀 구성원이 타깃 프로젝트에 추가되며, 팀 구성원 자격은 그대로 유지됩니다. 즉, 이 경로를 사용하여 팀 구성원을 실수로 "강등"시킬 수 없습니다. **초대한 사용자가 조직에 처음 참여하는 경우**, 귀하의 요청은 초대 흐름을 트리거하며 API는 다음과 같은 `pending_collaborator` 레코드로 응답합니다. ```json { "_type": "pending_collaborator", "email": "user@example.com", "id": "", "project_id": "" } ``` ### 프로젝트 협업자 제거 **참고:** 이 프로세스는 본질적으로 팀 멤버가 처리되는 방식(위 참조)과 동일합니다. 프로젝트에서 협업자를 제거하려면 다음이 필요합니다. 1. 타깃 프로젝트의 `id`. 2. 타깃 사용자의 이메일 주소. 이 시점에서, 귀하는 협업자를 추가할 때와 동일한 URL로 특수 쿼리 문자열을 전달하여 `DELETE` 호출을 수행하게 됩니다. `DELETE`[`https://api.frame.io/v2/projects/:id/collaborators/_?email=user@example.com`](ref:post_teams-teamid-members) 호출이 성공하면 API는 프로젝트 협업자 추가 시와 유사한 페이로드를 반환합니다. ```json { "_type": "collaborator", "creator_id": "", "id": "", "project_id": "", "user": { "_type": "user", <...> }, "user_id": "" } ``` 존재하지 않거나 해당 프로젝트와 연결된 적이 없는 협업자를 제거하려고 하면 404 오류가 발생합니다. 팀 구성원 제거와 달리, 이미 제거된 협업자를 다시 제거하려고 시도하면 404 오류가 발생합니다.