개인 액세스 토큰
개인 액세스 토큰(PAT)은 사용자가 직접 생성하여 붙여넣는 자격 증명입니다. Waafir REST API와 스크립트, 그리고 로그인할 수 없는 AI 어시스턴트를 위한 것입니다. 대부분의 어시스턴트는 Waafir URL을 붙여넣고 로그인하는 것만으로 연결되며, 토큰이 전혀 필요하지 않습니다. Waafir의 MCP 서버에서는 모든 요청에 로그인으로 생성된 연결이나 유효한 PAT 중 하나가 포함됩니다. 익명 접근은 없으며, 일반적인 로그인된 브라우저 세션은 이 인터페이스에서 허용되지 않습니다(세션으로 인증된 요청은 거부됨). PAT는 조직 내에서 사용자로서 작동하며, 발급할 때 선택한 범위와 데이터룸으로 제한됩니다.
토큰을 발급하는 곳
추가 기능 → 설정 → API 토큰을 엽니다. 이 페이지는 세 부분으로 구성됩니다. 새 토큰을 발급하는 양식, 기존 토큰 목록(취소 작업 포함), 그리고 토큰으로 어시스턴트를 연결하기 위한 바로 사용할 수 있는 구성 스니펫입니다.
토큰을 발급하려면 양식을 작성하세요.
- 이름 — 나중에 토큰을 알아볼 수 있도록 사람이 읽을 수 있는 레이블(예: "Claude Desktop – 노트북"). 필수입니다.
- 범위 — 토큰에 허용되는 작업. 아래를 참조하세요.
- 데이터룸 범위 — 모든 데이터룸을 선택한 채로 두면 토큰이 사용자가 접근할 수 있는 모든 데이터룸에 접근할 수 있고, 선택을 해제하고 특정 데이터룸을 고르면 토큰을 해당 데이터룸으로만 제한할 수 있습니다.
- 만료 — 이 날짜 이후에는 토큰이 작동하지 않습니다. 입력은 선택 사항이지만 실제로는 선택 사항이 아닙니다. 비워 두면 토큰은 90일 만료로 발급됩니다. 만료를 참조하세요.
범위
토큰은 세 가지 범위 중 하나를 가지며, 권한이 낮은 순서대로 다음과 같습니다.
| 범위 | 허용 내용 | 일반적인 용도 |
|---|---|---|
read | 목록 조회 및 읽기 — 데이터룸, 폴더, 파일, 파일 메타데이터, 검색, 다운로드 URL, 권한 보기. 문서에서 추출된 텍스트 읽기. 투자자 Q&A 스레드 읽기. 가림 처리, 번역 또는 전자 서명 작업의 상태 확인. | 데이터룸에 관한 질문에 답하는 읽기 전용 어시스턴트. |
write | read가 허용하는 모든 것에 더해 변경 작업: 폴더 생성, 이름 변경, 이동, 삭제, 복원. 파일 업로드, 이름 변경, 이동, 삭제, 복원(파일의 새 버전 업로드 및 롤백 포함). 문서 가림 처리 또는 번역 시작. 전자 서명 엔벨로프 생성, 발송, 거절, 무효화. 엔벨로프 발송(또는 이미 발송된 엔벨로프에 서명자 추가)에는 조직 외부 사람들에게 전송도 필요하며, 어시스턴트가 발송 전에 확인을 요청합니다. 서명(esign_sign)에는 문서 서명도 필요하며, 마찬가지로 먼저 확인을 받습니다. | 데이터룸을 정리하거나 유지 관리하는 어시스턴트. |
admin | write가 허용하는 모든 것에 더해 권한을 부여하는 도구 4개: 파일과 데이터룸에 대한 사용자의 접근 권한 부여 또는 취소. 권한을 읽는 도구 3개에는 read만 있으면 됩니다. | 누가 무엇을 볼 수 있는지 관리하는 어시스턴트. |
범위는 누적됩니다. 상위 범위는 그 아래의 모든 범위를 포함합니다. 각 서버의 도구 참조에는 도구마다 필요한 최소 범위가 명시되어 있습니다.
각 범위를 발급할 수 있는 사람
토큰은 발급한 사람보다 많은 권한을 가질 수 없습니다.
read및write범위는 조직의 모든 활성 구성원이 발급할 수 있습니다.admin범위는 조직 소유자 또는 관리자만 발급할 수 있습니다. 소유자나 관리자가 아니라면 범위 선택기에admin옵션이 표시되지 않습니다.- 투자자(및 딜 팀이 아닌 기타 역할)는 토큰을 전혀 발급할 수 없습니다.
발급 외에도 admin 권한 도구는 호출 시 두 번째 상한을 적용합니다. 권한 부여가 성공하려면 토큰 소유자 본인이 조직의 관리자 또는 매니저여야 합니다. 토큰의 범위는 토큰의 상한이고, 소유자의 역할은 사람의 상한이며, 관리자 작업은 둘 다 충족해야 합니다. 이는 제품 UI가 적용하는 규칙과 정확히 같습니다. MCP를 통한 경로가 제품을 통한 경로보다 느슨한 경우는 없습니다.
토큰에 문서 서명 허용
서명하려면 문서 서명이 켜진 토큰이 필요합니다. 이는 추가 기능 → 설정에서 write 또는 admin 토큰을 생성할 때 선택하므로, 신뢰하는 어시스턴트만 사용자를 대신해 서명할 수 있습니다. 2단계 인증을 켜 두었다면 토큰을 생성할 때 이미 2단계 인증 코드를 요청하므로, 이 확인이 해당 토큰이 하는 모든 서명에 적용됩니다. 토큰 목록에는 해당 토큰마다 서명 가능이 표시됩니다.
어시스턴트는 먼저 문서, 서명자, 필드를 보여 주고 사용자가 확인할 때만 서명합니다. 문서 서명이 없는 토큰의 도구 목록에는 esign_sign이 표시되지 않으며, 호출하면 거부됩니다. 이 옵션이 생기기 전에 생성된 토큰은 서명할 수 없습니다. 문서 서명을 켠 새 토큰을 생성하세요.
토큰에 문서 내용 읽기 허용
문서 전체를 읽거나 문서에 대해 AI에 질문하려면 문서 내용 읽기가 켜진 토큰이 필요합니다. 이는 추가 기능 → 설정에서 토큰을 생성할 때 선택하며, 모든 범위에서 가능합니다. 토큰 목록에는 해당 토큰마다 문서 내용이 표시됩니다. 적용 대상은 다음과 같습니다.
get_file_text: 문서에서 추출한 전체 텍스트.get_file_download_url: 파일 다운로드 링크.esign_download_signed: 서명된 전자 서명 PDF.- 완료된 번역에 대해
translate_file_status가 반환하는 다운로드 링크. GET /api/v1/files/{fileId}/content: REST API를 통한 문서 바이트.POST /api/viewer/token,POST /api/viewer/artifact-access,POST /api/viewer/artifact-access/unlock: 제품 내 문서 뷰어가 문서를 스트리밍할 때 사용하는 뷰어 토큰 또는 쿠키를 발급합니다.- 답변이 문서 내용을 그대로 옮길 수 있으므로, 사용자가 질문이나 입력을 작성하는 AI 도구:
dataroom_ask,dataroom_draft_answer,dataroom_compare_files,dataroom_generate_update. POST /api/v1/chat: REST API를 통한 동일한 AI 답변.GET /api/v1/facts가 반환하는 각 사실의quote.
이 권한이 없는 토큰은 해당 도구(GRANT_REQUIRED)와 해당 REST 경로(PAT_GRANT_REQUIRED)에서 거부되며, translate_file_status는 링크 대신 상태와 download_withheld_reason: content_grant_required를 반환합니다. GET /api/v1/facts와 dataroom_list_facts는 각 사실을 quote 없이 반환하고, value를 20단어로 자르며 value_truncated를 설정합니다. 토큰은 여전히 목록 조회와 검색을 할 수 있고, get_file_metadata 또는 dataroom_summarise_file로 문서 요약을 읽을 수 있습니다. 이 옵션이 생기기 전에 생성된 토큰은 문서 내용을 읽을 수 없습니다. 문서 내용 읽기를 켠 새 토큰을 생성하세요. 서비스 토큰은 영향을 받지 않습니다.
각 토큰은 분당 최대 10개의 다운로드 링크를 받을 수 있습니다. 이를 초과하면 get_file_download_url이 거부되고(RATE_LIMITED), translate_file_status는 상태와 download_withheld_reason: rate_limited를 반환합니다. 1분 후에 다시 요청하세요.
토큰에 조직 외부 사람들에게 전송 허용
공유 링크 생성, 스냅샷 뷰어 추가, 팀 구성원이나 투자자 초대, 투자자의 접근 연장 또는 복원(dataroom_extend_investor_access, dataroom_reinstate_investor_access)은 조직 외부의 누군가에게 접근 권한을 넘겨주는 작업이므로, 조직 외부 사람들에게 전송이 켜진 토큰이 필요합니다(투자자 업데이트, Q&A 답변, 전자 서명 요청을 보낼 때와 같은 권한입니다). 이는 추가 기능 → 설정에서 write 또는 admin 토큰을 생성할 때 선택합니다. 토큰 목록에는 해당 토큰마다 외부 전송 가능이 표시됩니다.
어시스턴트는 새 링크로 누가 접근할 수 있는지, NDA 규칙, 만료를 먼저 보여 주고 사용자가 확인할 때만 링크를 생성합니다. 링크나 뷰어를 취소하는 데는 별도 권한이 필요하지 않습니다.
이 권한은 딜 팀(소유자, 관리자, 구성원) 외부의 사람에게 데이터룸이나 문서에 대한 접근 권한 또는 더 많은 접근 권한을 주는 작업에도 적용됩니다. "외부"란 해당 데이터룸 조직의 활성 딜 팀 구성원이 아닌 모든 사람을 뜻합니다. 즉 투자자, 게스트, 초대가 대기 중인 사람, 다른 조직의 구성원입니다. 이 권한이 없으면 토큰은 다음 작업에서 거부됩니다(MCP에서는 GRANT_REQUIRED).
- 그러한 사람에게 읽기 또는 다운로드 권한 부여:
set_file_permissions,dataroom_set_folder_permissions,dataroom_bulk_set_file_permissions. - 그러한 사람에 대한 거부 해제(접근 권한이 복원됨):
revoke_file_permission,dataroom_revoke_folder_permission,dataroom_bulk_revoke_file_permissions. - 그러한 사람에게 수준과 관계없이 데이터룸 접근 권한 부여:
invite_user_to_dataroom. - 현재 역할이 딜 팀이 아닌 구성원의 역할 변경(승격에 해당):
dataroom_team_change_member_role. - 접근 범위를 넓히는 투자자 변경:
dataroom_set_investor_permissions로 뷰어에서 다운로더로 변경, NDA 끄기, 모니터링 또는 업데이트 켜기.
거부, 권한 부여 종료, 딜 팀에 대한 권한 부여에는 이 권한이 필요하지 않습니다. 이미 접근 권한이 있는 위치에 콘텐츠를 두는 작업(업로드, 이동, 게시)은 적용 대상이 아닙니다. 기업이 서명한 기업 NDA를 첨부하는 데도 이 권한이 필요하지 않습니다.
개인 액세스 토큰으로 수행하는 다음 REST 호출에도 같은 권한이 적용됩니다.
POST /api/share-links(링크 생성)와POST /api/snapshots/{id}/viewers는 이 권한이 없으면403 PAT_GRANT_REQUIRED로 거부됩니다.POST /api/investors/invite(개인 링크를 생성해 이메일로 보냄)도 같은 방식으로 거부됩니다.PATCH /api/investors/{id}/extend와PATCH /api/investors/{id}/access(투자자 복원 또는 접근 요청 승인)도 같은 방식으로 거부됩니다. 투자자 취소(DELETE /api/investors/{id}/access)에는 권한이 필요하지 않습니다.POST /api/team,POST /api/v1/team,POST /api/team/resend(팀 초대는 참여 링크를 이메일로 보냄)도 같은 방식으로 거부됩니다.PATCH /api/share-links/{id}는 링크의 접근 설정에 대한 모든 편집(켜기, 모드, 도메인, 만료 또는 NDA, 편집이 설정을 넓히든 좁히든 관계없음)에서 거부됩니다. 링크를 끄는 것은 항상 허용됩니다.GET /api/share-links는 각 링크의url과token을 제외하고 응답하며,urlWithheld: true로 표시하고 이유를 설명하는urlWithheldReason을 포함합니다.POST /api/v1/grants는 딜 팀 외부 사람에게 읽기 또는 다운로드 권한을 부여할 때 거부됩니다.DELETE /api/v1/grants/{id}는 해당 권한 부여가 그 사람에 대한 거부일 때 거부됩니다.PATCH /api/v1/team/{id}는 구성원의 현재 역할이 딜 팀이 아닐 때 거부됩니다.
이러한 검사는 서버가 라우팅하는 방식대로 경로를 읽으므로, 끝에 붙은 슬래시나 퍼센트 인코딩된 문자로 우회할 수 없습니다. 디코딩할 수 없는 경로, 또는 ./.. 세그먼트나 세그먼트 안에 인코딩된 /가 포함된 경로는 권한이 적용되는 어떤 호출과도 일치시킬 수 없습니다. 따라서 요청별 권한(이 권한, 문서 내용 읽기 또는 참여도 분석 읽기) 중 하나라도 없는 개인 액세스 토큰은 호출 종류와 관계없이 그러한 경로가 모두 403 PAT_PATH_MALFORMED로 거부됩니다.
이 권한이 생기기 전에 생성된 토큰은 이 권한을 가지고 있지 않으므로, 옵션을 켠 새 write 또는 admin 토큰을 생성할 때까지 이 호출들을 사용할 수 없습니다. read 토큰은 이 권한을 가질 수 없습니다.
토큰에 참여도 분석 읽기 허용
참여도 분석 읽기를 사용하면 토큰이 누가 어떤 문서를 언제, 얼마나 오래 보았는지 읽을 수 있습니다. 즉 참여도 도구와 투자자 명단의 참여도 정보입니다. 이를 보아야 하는 어시스턴트에만 켜세요. 모든 범위에서 가질 수 있습니다.
같은 권한이 REST 활동 읽기에도 적용됩니다: GET /api/v1/activity(조직의 활동 및 감사 피드), /api/v1/activity/rollups, /api/v1/activity/engagement, /api/v1/activity/engagement/documents, /api/v1/activity/engagement/document/pages. 이 권한이 없으면 개인 액세스 토큰은 403 PAT_GRANT_REQUIRED로 거부됩니다. 서비스 토큰과 로그인된 세션은 영향을 받지 않습니다.
이 옵션들이 생기기 전에 생성된 토큰은 둘 다 가지고 있지 않습니다. 옵션을 켠 새 토큰을 생성하세요.
특정 데이터룸으로 토큰 제한
기본적으로 토큰은 소유자가 접근할 수 있는 모든 데이터룸에 접근할 수 있습니다. 모든 데이터룸 선택을 해제하고 특정 데이터룸을 선택하면 토큰이 해당 허용 목록으로 제한됩니다. 목록 밖의 데이터룸을 참조하는 도구 호출은 모두 거부되며, 범위가 제한된 토큰은 열 수 없는 데이터룸의 이름조차 볼 수 없습니다. 이를 사용하면 포트폴리오의 나머지를 노출하지 않고 AI 클라이언트에 하나의 딜에 대한 접근 권한만 줄 수 있습니다.
만료
모든 토큰은 만료됩니다. 영구 PAT는 없습니다. 만료되지 않는 토큰 자체가 이 동작으로 해결하려는 보안 지적 사항이었습니다. 잊힌 자격 증명은 영원히 유효한 상태로 남기 때문입니다. 만료 날짜를 설정하면 토큰은 그 날짜 이후 작동을 멈춥니다. 만료된 토큰을 사용한 요청은 취소된 토큰과 똑같이 HTTP 401로 거부됩니다.
- 필드를 비워 두면 90일이 적용되며, 토큰이 발급된 순간부터 계산됩니다. 비워 두는 것은 기본값 사용을 뜻하며, 만료 없음을 뜻하지 않습니다.
- 날짜를 설정하면 그대로 정확히 적용되며, 상한은 발급일로부터 365일입니다.
- 365일을 초과하여 요청하면 요청이 거부되며, 조용히 단축되지 않습니다. 발급 과정에서 알리지 않고 요청보다 유효 기간이 짧은 토큰을 돌려주는 일은 없습니다. 과거 날짜도 같은 방식으로 거부됩니다.
따라서 통합을 계속 실행해야 한다면 만료를 의도적으로 설정하고, 토큰이 만료되기 전에 교체하도록 캘린더에 알림을 등록하세요. 필드를 비워 두면 설정 후 약 3개월 뒤에 해당 통합이 조용히 중단됩니다. 기존 토큰에는 갱신이나 순환 작업이 없으며, 만료 전 경고도 없습니다. 교체하려면 새 토큰을 발급하고, 클라이언트 구성을 업데이트하고, 이전 토큰을 취소해야 합니다. 반대로 일회성 작업을 위해 발급하는 토큰에는 짧은 만료가 딱 알맞습니다.
추가 기능 → 설정의 토큰 목록에는 각 토큰의 만료가 표시되므로, 곧 만료될 토큰을 확인할 수 있습니다.
1회 표시
토큰을 발급하면 원래 값(waafir_pat_로 시작)이 생성 직후 딱 한 번 표시됩니다. Waafir는 원래 토큰을 저장하지 않고 단방향 해시만 저장하므로, 토큰을 다시 가져오거나 다시 표시할 수 없습니다.
- 지금 복사하여 클라이언트 구성에 바로 붙여넣으세요. 표시 패널에 복사 버튼이 있습니다.
- 분실하면 복구할 수 없습니다. 해당 토큰을 취소하고 새 토큰을 발급하세요.
- 비밀번호처럼 취급하세요. 토큰을 가진 사람은 누구나 그 범위의 권한을 얻습니다.
표시 후 토큰 목록에는 비밀이 아닌 짧은 접두사(예: waafir_pat_ab12…)만 표시되므로, 비밀 값을 복구할 수 없는 상태에서도 토큰을 구별할 수 있습니다.
토큰 취소
추가 기능 → 설정의 토큰 목록에서 원하는 토큰 옆의 취소 작업을 사용하세요. 취소는 즉시 적용되며, 해당 토큰을 사용하는 다음 요청은 거부됩니다. 기기를 분실했거나, 계약자가 떠났거나, 단순히 더 이상 접근 권한이 필요하지 않다면 즉시 토큰을 취소하세요. 취소된 토큰은 목록에 계속 표시되어(취소됨으로 표시) 존재했던 토큰의 기록이 보존되며, 다시 활성화할 수 없습니다.
토큰이 자동으로 종료되는 경우
토큰은 조직 구성원 자격을 통해 작동하므로, 그 구성원 자격이 끝나면 토큰도 종료됩니다. 다음 경우에는 직접 취소할 필요가 없습니다.
- 조직을 떠나거나 관리자가 사용자를 제거한 경우. 해당 조직에서 보유한 모든 토큰이 그 순간 취소됩니다. 다른 조직에서 보유한 토큰은 계속 작동합니다.
- Waafir 관리자가 사용자 계정을 삭제한 경우. 모든 조직에 있는 사용자의 토큰이 취소됩니다.
- Waafir 관리자가 조직을 삭제한 경우. 서비스 토큰을 포함해 해당 조직의 모든 토큰이 취소됩니다.
이러한 취소는 영구적입니다. 다시 초대를 받거나 계정 또는 조직이 복원되더라도 토큰이 되살아나지 않습니다. 새 토큰을 발급하세요.
서비스 토큰은 생성한 관리자가 아니라 조직에 속하므로, 그 관리자가 떠나도 계속 작동합니다. 취소하거나 조직을 삭제하는 경우에만 조기에 종료됩니다.
감사 로그의 토큰 기록
토큰을 발급하거나 취소할 때마다 조직의 감사 로그에 한 행이 기록됩니다. 수행한 사람, 토큰의 이름, 범위, 권한 및 만료, 제한된 데이터룸 수, 취소된 이유(소유자에 의한 취소, 구성원 자격 종료, 계정 또는 조직 삭제)가 기록됩니다. 토큰 자체, 해시, 접두사는 절대 기록되지 않습니다. 이 행들은 대시보드 요약이 아니라 전체 활동 기록에 표시됩니다.
Waafir가 새 토큰을 감사 로그에 기록할 수 없으면 토큰이 발급되지 않으며, "The token wasn't created because we couldn't record it. Try again."(토큰을 기록할 수 없어 생성되지 않았습니다. 다시 시도하세요.)이라는 메시지가 표시됩니다.
다음 단계: 방금 발급한 토큰으로 클라이언트를 설정하세요.