PDFLoom Logo

Authentication

To ensure secure access to the PDFLoom API, all requests must be authenticated using a bearer token. This token verifies that the request is coming from a trusted source and has the necessary permissions to perform the requested operations.

Generating Your API Token

  1. Log In: Log in to your PDFLoom account.
  2. Navigate to API Page: Go to the API page in your dashboard.
  3. Generate Token: Click on "Generate New Token" to create a new bearer token.
  4. Store Securely: Store this token securely. Do not share it publicly or include it in client-side code.

Please don't commit your PDFLoom API Key to GitHub!

Using the API Token

Include the token in the Authorization header of each API request. The format should be as follows. Here's how to add the token to the request header using cURL:

Example request with bearer token

curl -X POST https://api.pdfloom.com/v1/convert/html \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "content": "<html><body><h1>Hello World</h1></body></html>",
    "options": {
      "format": "A4",
      "landscape": false
    }
  }'

Token Expiration and Regeneration

Tokens may have an expiration date for security purposes. If your token expires or you believe it has been compromised, you can generate a new token from the API page in your PDFLoom dashboard.

Security Best Practices

  • Keep your token secure: Treat your API token like a password. Do not expose it in client-side code, public repositories, or anywhere it can be accessed by unauthorized users.
  • Use HTTPS: Ensure that all your requests to the PDFLoom API are made over HTTPS to prevent eavesdropping and man-in-the-middle attacks.
  • Rotate your token periodically: Regularly regenerate your API token to minimize the risk in case it gets compromised.
  • By following these practices, you can ensure that your interactions with the PDFLoom API remain secure and reliable. If you encounter any issues with authentication, please contact our support team at support@pdfloom.com.

Token Scopes

API tokens can be scoped to limit access to specific operations. When creating a token, you can specify which endpoints it can access. This follows the principle of least privilege—granting only the permissions needed for each use case.

Available Scopes

  • Name
    convert:pdf
    Type
    scope
    Description

    Allow PDF conversion endpoints (/v1/convert/html, /v1/convert/url, /v1/convert/docs).

  • Name
    convert:screenshot
    Type
    scope
    Description

    Allow screenshot endpoints (/v1/screenshot/html, /v1/screenshot/url).

  • Name
    convert:docs
    Type
    scope
    Description

    Allow document conversion endpoint (/v1/convert/docs).

  • Name
    read:credits
    Type
    scope
    Description

    Allow reading credit balance (/v1/account/credits).

  • Name
    read:tokens
    Type
    scope
    Description

    Allow listing API tokens (/v1/tokens).

  • Name
    read:requests
    Type
    scope
    Description

    Allow reading request history (/v1/requests).

Scope Enforcement

If a token lacks the required scope for an endpoint, you'll receive a 403 Forbidden error with details about the missing permission:

Insufficient scope error

{
  "success": false,
  "error_code": "INSUFFICIENT_SCOPE",
  "message": "This token does not have the required scope: convert:pdf",
  "required_scope": "convert:pdf",
  "token_scopes": ["read:credits", "read:requests"]
}

Scope-to-Endpoint Mapping

The following table shows which scopes are required for each endpoint:

EndpointRequired Scope
/v1/convert/htmlconvert:pdf
/v1/convert/urlconvert:pdf
/v1/convert/docsconvert:docs
/v1/screenshot/htmlconvert:screenshot
/v1/screenshot/urlconvert:screenshot
/v1/account/creditsread:credits
/v1/tokensread:tokens
/v1/requestsread:requests

Best Practice: Create tokens with minimal scopes needed for each use case. For example, a monitoring script should only have read:credits and read:requests scopes, not conversion permissions.

Example: Scoped Token Usage

Create separate tokens for different purposes:

Production API Token (full conversion access):

  • Scopes: convert:pdf, convert:screenshot, convert:docs

Monitoring Script (read-only access):

  • Scopes: read:credits, read:requests

Screenshot Service (screenshot-only):

  • Scopes: convert:screenshot, read:credits

This approach limits the damage if a token is compromised—a leaked monitoring token cannot consume credits or generate conversions.

Was this page helpful?