인증
ZeroTalk Public API는 **Personal Access Token(PAT)**으로 인증합니다. PAT는 워크스페이스 단위로 발급되는 토큰으로, 부여된 scope 범위 안에서만 데이터를 조회할 수 있습니다.
토큰 형식
PAT는 ztpat_ prefix로 시작하는 49자 문자열입니다.
ztpat_AB12CD…(base64url)
앞 12자(ztpat_AB12CD)는 토큰을 식별하는 prefix로 대시보드 토큰 목록에 표시됩니다. 나머지는 발급 시 한 번만 노출되는 비밀 값입니다.
발급
워크스페이스 Owner 또는 Admin 권한이 필요합니다 (상담원·뷰어 역할은 발급할 수 없습니다).
- 대시보드에서 설정 → 개발자(Settings → Developers) 페이지로 이동합니다
- 토큰 생성을 클릭하고 토큰 이름, 부여할 scope, 만료 기간(기본 90일)을 선택합니다
- 발급된 토큰을 안전한 곳에 저장합니다 — 평문은 이때 한 번만 표시됩니다
주의
토큰은 발급 시 한 번만 표시되며 이후 평문을 다시 확인할 수 없습니다. 분실하면 재발급(rotate)해야 합니다.
scope는 <domain>:read 형식의 fine-grained 권한입니다. 모든 토큰에는 workspaces:read가 기본으로 자동 포함되며, 그 외 scope는 발급 시 선택합니다. 전체 목록은 스코프 문서를 참고하세요.
사용 방법
모든 요청의 Authorization 헤더에 Bearer 토큰으로 전달합니다.
curl https://api.talk.zeroworks.ai/api/public/v1/workspace \
-H "Authorization: Bearer ztpat_..."
만료
토큰에는 선택적으로 만료일(expires_at)을 둘 수 있습니다. 설정하지 않으면 영구 유효하지만, 보안상 90일 만료를 권장합니다.
회전(Rotation)과 폐기(Revoke)
- 회전: 새 토큰을 발급하고 기존 토큰을 즉시 무효화합니다. 서버 측 grace 기간이 없으므로, 호출 측에서 새 토큰으로 교체한 뒤 회전하세요.
- 폐기: 토큰을 즉시 비활성화합니다. 폐기된 토큰으로 보낸 요청은
401 INVALID_TOKEN을 반환합니다. - 토큰이 노출된 경우 즉시 폐기·재발급하고 audit log를 검토하세요.