제품 및 API 안내

인증

키의 용도

모든 호출에는 하나의 키가 포함됩니다. 키는 개인이 아닌 워크스페이스에 속하므로 누군가 나가도 계속 작동합니다. 계정의 API 키에서 만들며 비밀 키는 한 번만 표시되고 수행 가능한 작업은 권한 범위로 정해집니다.

모든 요청에는 API 키가 포함됩니다. 계정의 API 키 화면에서 생성하며 생성 시 한 번만 표시되고 읽을 수 있는 형태로 저장되지 않습니다.

X-PDFgine-Key: pdfgine_live_xxxxxxxxxxxxxxxxxxxxxxxx

브라우저나 모바일 앱에 키를 포함하지 마세요. 자체 서버에서 호출하세요.

각 키에는 권한 집합이 있으므로 문서 생성만 허용된 키는 템플릿을 수정할 수 없습니다.

templates:read   templates:write   documents:render
previews:manage  assets:read       assets:write
usage:read       api-keys:manage

성공하는 호출과 실패하는 호출

첫 호출은 템플릿 목록을 조회합니다. 두 번째는 취소된 키를 보내며 응답에서 그 사실을 명확히 알려 줍니다.

cURL 
# 키는 코드가 아닌 환경 변수에 설정
export PDFGINE_KEY="pdfgine_live_..."

curl -i https://api.pdfgine.com/api/v1/templates \
  -H "X-PDFgine-Key: $PDFGINE_KEY"
응답 
HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.2",
  "title": "Unauthorized request",
  "status": 401,
  "detail": "The API key is invalid.",
  "correlationId": "0123b82d0a59e8b196a783af0e0e86bc"
}

모든 오류 본문에는 correlationId가 포함됩니다. 지원팀에 문의할 때 전달하면 추측 없이 로그에서 요청을 찾을 수 있습니다.

자주 발생하는 문제

  • 키는 X-PDFgine-Key 헤더에 넣습니다. Authorization: Bearer 토큰은 전혀 읽지 않으므로 키가 유효해도 401로 응답합니다.
  • 401과 403은 다릅니다. 401은 “인증할 수 없음”, 403은 “인증되었으나 이 키에 해당 권한이 없음”을 뜻합니다. templates:write가 없는 키는 템플릿을 저장할 수 없습니다. 권한은 키를 만들 때 정해집니다.
  • 비밀 키는 한 번만 표시됩니다. 잃어버리면 다시 읽을 수 없으므로 해당 키를 취소하고 새로 만드세요.
  • 키를 브라우저나 모바일 앱에 넣지 마세요. 기기에 배포된 내용은 읽어 낼 수 있으므로 자체 서버에서 PDFgine을 호출하세요.
  • 취소는 바로 다음 호출부터 적용됩니다. 새 키를 먼저 배포한 후 이전 키를 취소하세요. 순서를 바꾸면 진행 중인 호출이 실패합니다.