Waafir
이 페이지는 사람의 검토를 기다리는 기계 번역입니다. 오류가 있을 수 있습니다.

인증

모든 /v1 요청은 인증을 거칩니다. 자체 시스템에서는 Bearer 토큰으로 전송하는 개인 액세스 토큰(PAT)으로 인증합니다.

Authorization: Bearer waafir_pat_…

토큰은 추가 기능 → 설정에서 발급, 제한, 취소합니다. 개인 액세스 토큰 가이드에서 발급, 만료(기본 90일, 최대 365일), 일회성 표시, 취소를 다룹니다. 이 규칙은 플랫폼 API에도 똑같이 적용됩니다. 이 페이지에서는 토큰을 보유한 뒤 그 토큰으로 무엇을 할 수 있는지 설명합니다.

개인 액세스 토큰은 토큰을 발급한 사람으로서, 그 사람의 조직 안에서 작동합니다. 토큰이 이미 조직을 고정하므로 어떤 URL이나 본문에도 조직 매개변수는 없습니다.

세 가지 토큰 검사

토큰으로 인증된 요청은 무엇보다 다음 세 가지 검사를 통과해야 합니다. 조직 보안 정책과 엔드포인트 자체의 검사도 요청을 거부할 수 있습니다(아래 참조). 세 가지 중 두 가지에는 고유한 코드가 있습니다. 역할 거부는 다른 거부와 공유하는 FORBIDDEN으로 응답할 수 있으므로, 코드를 엔드포인트의 요구 사항과 함께 읽으세요.

검사질문거부
토큰 범위토큰의 범위가 이 엔드포인트의 작업을 포함하는가?PAT_SCOPE_INSUFFICIENT 403
역할호출자가 이 엔드포인트에 필요한 역할을 가지고 있는가?FORBIDDEN 403 또는 PAT_ROLE_CEILING 403
데이터룸데이터룸 제한 토큰의 경우, 이 데이터룸이 목록에 있는가?PAT_DATAROOM_SCOPE 403

토큰 범위

토큰은 read, write, admin 중 하나의 범위를 가지며, 이 순서대로 권한이 커집니다. 상위 범위는 그 아래의 모든 범위를 포함합니다.

엔드포인트에 필요한 범위는 기본적으로 HTTP 메서드를 따릅니다.

  • GET, HEAD, OPTIONS에는 read가 필요합니다.
  • 그 밖의 모든 메서드(POST, PATCH, PUT, DELETE)에는 write가 필요합니다.

일부 엔드포인트는 다른 범위를 선언합니다. 대표적인 경우는 쿼리만 실행하는 POST로, 이때는 read만 있으면 됩니다. 엔드포인트 레퍼런스에 각 엔드포인트가 실제로 요구하는 범위가 표시되므로, 메서드로 추론하지 말고 그곳에서 확인하세요.

필요 역할과 역할 상한

범위는 토큰이 무엇을 할 수 있는지를 말합니다. 엔드포인트의 필요 역할은 사람이 누구여야 하는지를 말합니다. 많은 /v1 엔드포인트는 딜 팀(조직 소유자, 관리자 또는 구성원)을 요구합니다. 팀 변경과 접근 권한 부여 변경 등은 소유자나 관리자를 요구합니다. 투자자와 기타 게스트는 딜 팀 역할이 없으므로 딜 팀 엔드포인트에서 거부됩니다. 다른 엔드포인트는 인증 계층에서 역할 게이트를 선언하지 않고 대신 엔드포인트 내부에서 접근을 확인합니다. 예를 들어 포트폴리오 모니터링 경로는 모니터링 추가 기능과 호출자의 모니터링 접근 권한을 확인합니다. 엔드포인트 레퍼런스에 각 엔드포인트의 역할 게이트가 표시됩니다. 선언된 게이트가 없더라도 엔드포인트 자체가 거부할 수 있다는 점을 염두에 두세요.

토큰은 또한 발급 시점의 발급자 역할을 상한으로 기록합니다. Waafir가 적용하는 역할은 발급자의 현재 역할과 이 상한 중 낮은 쪽입니다. 나중에 관리자로 승격된 구성원도 이전에 발급한 토큰으로는 여전히 구성원으로 작동하므로, 새 역할을 사용하려면 새 토큰을 발급하세요. 역할이 낮아진 사람은 토큰에 무엇이 기록되어 있든 즉시 해당 권한을 잃습니다. 어느 쪽이든 권한이 부족하면 403의 FORBIDDEN 또는 PAT_ROLE_CEILING으로 거부됩니다.

데이터룸 제한 토큰

모든 데이터룸 대신 특정 데이터룸을 선택하여 발급한 토큰은 해당 데이터룸에만 접근할 수 있습니다. 다른 데이터룸을 지정하는 요청은 PAT_DATAROOM_SCOPE로 거부됩니다. 일부 조직 전체 엔드포인트는 응답이 토큰이 볼 수 없는 데이터룸까지 걸쳐 있기 때문에 제한 토큰을 같은 코드로 아예 거부합니다. 이러한 엔드포인트에는 제한 없는 토큰을 사용하세요. GET /api/v1/session은 두 종류 모두 허용합니다.

그 밖에 마주칠 수 있는 거부

  • 401 UNAUTHORIZED: Authorization 헤더가 없거나, 토큰을 알 수 없거나, 만료되었거나, 취소된 경우입니다.
  • 다른 조직의 리소스에 대한 404. 다른 조직에 속한 ID는 찾을 수 없는 것으로 처리되므로, 그 존재 여부가 확인되지 않습니다.
  • 제한된 파일에 대한 소유자/관리자 예외 없음. 앱에서는 조직 소유자나 관리자가 모든 제한된 파일을 볼 수 있습니다. 토큰은 그렇지 않습니다. 토큰은 소유자가 직접 만들었거나 권한을 부여받은 제한된 파일에만 접근할 수 있습니다. 읽을 수 없는 파일을 지정한 요청은 존재하지 않는 파일과 같은 응답(/api/v1/grants의 경우 파일을 지정하는 400 또는 권한 부여에 대한 404)을 받으며, "not found, or not readable by this credential"이라는 메시지가 표시되므로 응답이 파일의 존재를 확인해 주는 일은 없습니다.
  • 조직 보안 정책. 조직에 IP 허용 목록이 있으면 목록 밖에서 온 요청은 IP_BLOCKED로 응답합니다. 2단계 인증 강제 적용은 MFA_SETUP_REQUIRED 또는 MFA_CHALLENGE_REQUIRED로 응답할 수 있습니다.
  • 429 RATE_LIMITED. 일부 엔드포인트는 신원별 분당 상한을 선언하며, 이는 엔드포인트에 표시됩니다. 나머지는 플랫폼 기본값을 사용합니다. 잠시 기다린 후 다시 시도하세요.

오류 코드 페이지에 알려진 코드와 그 의미가 나열되어 있습니다.