PDFengine Logo

Authentication & Security

Learn how to securely authenticate with the PDFen API using tokens, manage credentials, and follow security best practices.

On This Page

All Guides

Getting Started Authentication Use Cases Best Practices Migration (v1 → v2) Claude MCP Server (EN) Claude MCP Server (NL)

Overview

PDFen API uses Bearer token authentication with Laravel Sanctum. Tokens are secure, easy to manage, and can be revoked instantly without changing your password.

Recommended Method

API tokens are the recommended authentication method for both v1 and v2 APIs. Username/password authentication (v1 only) will be disabled after 6 months.

Generating API Tokens

Step-by-Step:

  1. Navigate to Profile → API Tokens
  2. Click "Create New Token"
  3. Enter a descriptive name (e.g., "Production Server", "Staging Environment")
  4. Select permissions (default: all)
  5. Click "Generate"
  6. Copy the token immediately - it's only shown once!

Using Your Token:

curl https://pdfen.com/api/v2/user \
  -H "Authorization: Bearer 1|abc123def456..."

Token Security

The token is displayed only once. Store it securely. If lost, you'll need to generate a new token.

Security Best Practices

✓ DO: Use Environment Variables

Never hardcode tokens in your source code.

# .env file
PDFEN_API_TOKEN=1|abc123def456...
// PHP
$token = getenv('PDFEN_API_TOKEN');

✓ DO: Use Different Tokens Per Environment

Create separate tokens for development, staging, and production.

✗ DON'T: Commit Tokens to Git

Add .env to your .gitignore file.

✗ DON'T: Share Tokens

Each developer/server should have its own token.

✓ DO: Rotate Tokens Regularly

Generate new tokens every 90 days for security.

✓ DO: Revoke Unused Tokens

Delete tokens that are no longer needed.

Rate Limits

Free Users

100

requests per hour

Paid Users

1,000

requests per hour

Rate Limit Headers:

HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 950
X-RateLimit-Reset: 1705320000

Handling Rate Limits:

<?php
$response = $client->request('GET', '/api/v2/user');
$remaining = $response->getHeader('X-RateLimit-Remaining')[0];

if ($remaining < 10) {
    // Slow down requests
    sleep(60);
}

Error Handling

Authentication Errors:

401 Unauthorized

{
  "error": "Unauthenticated",
  "message": "Invalid or missing API token"
}

Solution: Check your token is correct and not revoked.

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "retry_after": 3600
}

Solution: Wait for the specified time or upgrade your account.

403 Forbidden

{
  "error": "Insufficient permissions",
  "required_ability": "convert:create"
}

Solution: Generate a new token with the required permissions.

Token Rotation Strategy

For maximum security, rotate your API tokens every 90 days. Here's how to do it without downtime:

Zero-Downtime Rotation:

  1. Generate a new API token (keep the old one active)
  2. Update your application configuration with the new token
  3. Deploy the updated configuration
  4. Verify the new token works in production
  5. Wait 24 hours for caches to clear
  6. Revoke the old token

Automated Rotation (PHP Example):

<?php
// Check token age
$tokenCreatedAt = strtotime($token->created_at);
$daysSinceCreation = (time() - $tokenCreatedAt) / 86400;

if ($daysSinceCreation > 90) {
    // Trigger alert for manual rotation
    notify_admins('API token needs rotation');
}