製品・APIガイド

認証

キーの役割

すべての呼び出しに1つのキーを指定します。キーは個人ではなくワークスペースに属するため、メンバーが退出しても動作し続けます。「アカウント → 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

成功する呼び出しと、失敗する呼び出し

最初の呼び出しは、テンプレート一覧を取得します。2つ目は、取り消されたキーを送信し、そのことがレスポンスに明記されます。

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は、ご自身のサーバーから呼び出してください。
  • キーの取り消しは、次の呼び出しから直ちに適用されます。先に新しいキーをデプロイし、その後古いキーを取り消してください。順序を逆にすると、実行中の呼び出しが失敗します。