본문으로 건너뛰기

인증

제로톡 Public API는 Personal Access Token(PAT) 으로 인증합니다. PAT는 워크스페이스 단위로 발급하는 토큰이고, 발급할 때 부여한 scope 범위 안에서만 호출할 수 있습니다.

토큰 형식​

PAT는 ztpat_ prefix로 시작하는 49자 문자열입니다.

ztpat_AB12CD…(base64url)

앞 12자(ztpat_AB12CD)는 토큰을 식별하는 prefix이며 대시보드 토큰 목록에 표시됩니다. 나머지는 발급할 때 한 번만 보여 주는 비밀 값입니다.

발급​

워크스페이스 Owner(소유자) 권한이 필요합니다. 관리자·상담원·뷰어 역할은 발급할 수 없습니다.

  1. 대시보드의 채팅 설정 > 연동 / 개발 > 개발자 페이지로 이동합니다.
  2. + 토큰 생성을 클릭하고 토큰 이름, 부여할 scope, 만료 기간, 허용 IP(선택)를 정합니다. 만료 기간은 30일·60일·90일·365일·무기한 중에서 고르며 기본값은 90일입니다. 토큰 이름은 80바이트 이하(한글은 한 글자에 3바이트)이고, 같은 이름의 토큰은 만들 수 없습니다.
  3. 발급된 토큰을 안전한 곳에 저장합니다. 평문은 이때 한 번만 표시됩니다.
주의

토큰은 발급할 때 한 번만 표시되며, 이후에는 평문을 다시 확인할 수 없습니다. 분실하면 회전(rotate)해서 새 토큰을 받아야 합니다.

scope는 <domain>:read, <domain>:write 형식의 세분화된 권한입니다. 모든 토큰에는 workspaces:read가 자동으로 들어가고, 나머지 scope는 발급할 때 고릅니다. 엔드포인트별로 필요한 scope는 스코프 문서에 있습니다.

사용 방법​

모든 요청의 Authorization 헤더에 Bearer 토큰으로 전달합니다. 아래 명령은 워크스페이스 정보를 조회합니다.

curl https://api.talk.zeroworks.ai/api/public/v1/workspace \
  -H "Authorization: Bearer ztpat_..."

만료​

토큰은 발급할 때 정한 만료일(expires_at)이 지나면 쓸 수 없습니다. 만료된 토큰으로 보낸 요청은 401 INVALID_TOKEN을 반환합니다. 대시보드에서 무기한을 고르면 만료되지 않지만, 보안을 위해 90일 만료를 권장합니다.

허용 IP​

토큰마다 허용 IP를 정할 수 있습니다. 허용 IP 칸에 203.0.113.5 같은 주소나 203.0.113.0/24 같은 대역을 입력하면, 그 주소에서 온 요청만 받습니다. 비워 두면 IP를 제한하지 않습니다.

허용 목록에 없는 주소에서 호출하면 403 IP_NOT_ALLOWED_WORKSPACE를 반환하고, 응답의 error.client_ip에 서버가 확인한 호출 주소를 담습니다. 이 값을 허용 IP에 추가하거나, 토큰을 쓰는 서버의 외부 주소를 확인할 때 사용하세요.

회전(Rotation)과 회수(Revoke)​

  • 회전: 기존 토큰을 즉시 무효로 만들고, 같은 이름·scope의 새 토큰을 발급합니다. 서버에는 유예 기간(grace period)이 없으므로, 호출하는 쪽에서 새 토큰으로 교체할 준비를 마친 뒤에 회전하세요. 허용 IP는 회전할 때 바꾸지 않으면 기존 토큰의 목록을 이어받습니다. 새 토큰을 만드는 작업이라 발급과 같은 Owner 권한이 필요합니다.
  • 회수: 토큰을 즉시 비활성화합니다. 회수된 토큰으로 보낸 요청은 401 INVALID_TOKEN을 반환합니다. Owner 또는 Admin 권한으로 회수할 수 있습니다.
  • 토큰이 노출되면 즉시 회수하고 새 토큰을 발급하세요. 노출 이후의 호출 이력은 audit log에서 확인하세요.

인증이 안 될 때​

  • 401 MISSING_TOKEN: Authorization 헤더가 없거나 Bearer 뒤의 값이 비어 있습니다. 헤더 형식은 Authorization: Bearer ztpat_...입니다.
  • 401 INVALID_TOKEN: 토큰이 ztpat_로 시작하지 않거나, 철자가 틀렸거나, 만료되었거나, 회수되었습니다. 대시보드 토큰 목록에서 상태를 확인하고, 만료·회수된 토큰이면 새로 발급하세요.
  • 403 INSUFFICIENT_SCOPE: 토큰에 필요한 scope가 없습니다. 응답의 error.details.required_scope가 빠진 scope입니다. scope는 발급 후에 바꿀 수 없으므로 필요한 scope를 넣어 새로 발급하세요.
  • 403 IP_NOT_ALLOWED_WORKSPACE: 호출한 주소가 토큰의 허용 IP에 없습니다.

모든 오류 코드는 에러 문서에서 확인할 수 있습니다.