본문으로 건너뛰기

시작하기

인증

키가 워크스페이스를 식별하는 방식, 키가 허용하는 것, 키를 보호하는 방법.

키는 워크스페이스와 멤버를 식별하며, 할 수 있는 일의 목록을 담고 있습니다. 이 페이지에서는 키를 보내는 방법, 키가 허용하는 것, 한도, 키를 보호하는 방법을 설명합니다.

키 보내기#

공개 라우트인 GET/api/v1과 GET/api/v1/openapi.json을 제외한 모든 라우트는 Authorization 헤더에 키를 요구합니다.

HTTP
Authorization: Bearer piq_live_…

Authorization을 설정할 수 없는 클라이언트를 위해 x-api-key: piq_live_… 헤더도 사용할 수 있습니다.

키는 piq_live_로 시작하고 38자가 이어집니다. 설정 화면에는 접두사 뒤의 처음 6자가 표시되어 키를 알아볼 수 있습니다. 나머지는 다시 표시되지 않습니다.

키가 나타내는 것#

키는 키를 만든 멤버를 대신하여, 그 멤버의 워크스페이스에서, 그 멤버의 역할로 동작합니다. 대시보드의 규칙이 그대로 적용됩니다. 키는 다른 워크스페이스를 볼 수 없으며, 키를 만든 사람이 워크스페이스를 떠나면 키도 작동을 멈춥니다.

키는 소유자와 관리자만 설정 → API 및 MCP에서 만들 수 있습니다. 워크스페이스당 활성 키는 최대 25개입니다.

스코프#

스코프는 도구 한 계열을 엽니다. 각 도구는 자체 스코프를 요구하며, 카탈로그에 표시됩니다.

스코프허용 범위
read코퍼스와 워크스페이스 읽기: 소스, 항목, 주제, 신호, 엔티티, 보드, 테이블, Upwork 파이프라인.
explore웹, 소셜 네트워크, 등록부, 아카이브를 실시간으로 읽기. 워크스페이스 크레딧을 사용합니다.
write워크스페이스에 쓰기: 보드, 테이블, 팔로우 중인 엔티티, 모니터링 계약, 프로필, Upwork 초안.
act모니터링에 대한 실행: 소스 구독 또는 구독 취소, 신호 규칙 설정, 조사 시작, 캠페인 팔로우.
agentsPiqline, Requête, Facebook, LinkedIn, Upwork, 온보딩 에이전트가 답하게 하기. 워크스페이스 크레딧을 사용합니다.

필요한 최소한만 선택하십시오. 코퍼스를 읽는 데는 read로 충분하고, 에이전트가 답하게 하려면 agents를 추가합니다. 키로 실행한 에이전트는 키가 직접 호출할 수 있는 도구만 사용합니다.

만료와 폐기#

키는 만료되지 않게 하거나, 90일 또는 1년 후에 만료되도록 설정할 수 있습니다. 폐기하려면 설정 → API 및 MCP를 열고 폐기를 클릭한 다음 키 폐기를 클릭합니다. 해당 키를 사용하는 호출은 1분 안에 401을 받습니다.

한도#

키별 한도기본값초과 시
분당 요청 수120429 rate_limited, Retry-After 포함
분당 에이전트 턴 수10429 rate_limited, Retry-After 포함
일일 요청 수20,000429 quota_exceeded

모든 응답에는 RateLimit-Limit(분당 허용되는 버스트)와 RateLimit-Remaining(남은 횟수)가 포함됩니다. 분당 한도는 버스트를 늦추는 용도입니다. 서버 인스턴스별로 적용되므로 표시된 값보다 약간 더 많이 통과할 수 있습니다. GET/api/v1/workspace는 키의 한도와 오늘 보낸 요청 수를 반환합니다.

사용량과 기록#

설정 → API 및 MCP에서 최근 30일의 도구별, 에이전트별 사용량과 각 요청의 기록을 볼 수 있습니다. 기록에는 시간, 작업, 상태, 소요 시간, 오류, 입력 발췌, 클라이언트, 출발지 네트워크가 담깁니다. 기록은 30일간 보관됩니다.

기록에는 키도 요청 본문 전체도 들어 있지 않습니다. 입력 발췌는 300자에서 잘리고, 비밀 정보로 보이는 필드(password, token, key)는 마스킹되며, 네트워크 접두사(IPv4는 /24, IPv6는 /48)만 보관하고 전체 IP 주소는 보관하지 않습니다.

키 보호하기#

  • 시크릿 관리자나 환경 변수에 보관하십시오. 저장소, 웹 페이지, 모바일 앱에는 넣지 마십시오.
  • 용도마다(스크립트, 에이전트, 동료) 키를 하나씩 만들고 알아볼 수 있는 이름을 붙이십시오. 다른 키에 영향을 주지 않고 하나만 폐기할 수 있습니다.
  • 테스트용 키에는 만료 기간을 설정하십시오.
  • 노출된 키는 즉시 폐기하십시오. Piqline은 키의 지문만 보관하므로 키를 다시 알려 드릴 수 없고, 새 키를 만드는 것만 가능합니다.
  • 키는 만든 사람의 권한을 유지하며, 그 사람이 팀을 떠나면 작동을 멈춥니다. 장기간 사용하려면 연동 전용 계정으로 키를 만드십시오.

API에 대한 질문이 있거나 이 페이지에 오류가 있나요? 문의하기.