Authentication

1. How Authentication Works

The Pdffillr API uses API key authentication. Every request the SDK sends to the API includes your key in the Authorization HTTP header as a bearer token. The API server validates the key on every request - there is no separate login step, no session cookie, and no token expiry to manage. If the key is valid, the request proceeds; if it is missing, malformed, or revoked, the server returns a 401 Unauthorized response immediately.

You do not need to write any authentication code yourself. The SDK reads your API key from the constructor options and attaches it to every outbound request automatically. From your application's perspective, authentication is a one-time configuration step at startup - after that, every call to client.sdk.* is authenticated without any additional work on your part.

2. Your API Key

Your API key is a long, randomly generated string that uniquely identifies your Pdffillr account. It is displayed only once when you create it - copy it immediately and store it somewhere secure, such as a password manager or a secrets vault. If you lose it, you will need to generate a new one and update all environments that use the old key.

3. Environment Variable (Recommended)

The recommended way to supply your API key is through an environment variable. You can name the variable anything you like - PDFFILLR_API_KEY is just a common convention, not a requirement. Whatever name you choose, pass its value to the apiKey constructor option and the SDK will use it for every request. This pattern keeps your secret out of source code entirely - it lives only in your runtime environment, never in a file that could be committed, cached, or logged.

# .gitignore  -  add these before your first commit
.env
.env.local
.env.development
.env.staging
.env.production

# .env
# You can name this variable anything you like - the name shown here is
# just a convention. Pass whatever name you choose to the apiKey option.
# Never commit this file to version control.
PDFFILLR_API_KEY=your_api_key_here

# Custom variable name - works exactly the same way:
# MY_APP_PDFFILLR_KEY=your_api_key_here

// src/index.ts  -  load env vars before any other import
import 'dotenv/config';

import Pdffillr from '@pdffillr/sdk';

// Pass whichever env variable name you chose - the SDK accepts any value
// supplied to the apiKey option, regardless of what the variable is called.
const client = new Pdffillr({
  apiKey: process.env['PDFFILLR_API_KEY'],
  // or: apiKey: process.env['MY_APP_PDFFILLR_KEY'],
});

4. Explicit Key in Constructor

You can pass the API key directly to the constructor through the apiKey option. The SDK treats an explicitly provided key identically to one read from the environment - it is attached to every request in the Authorization header. The difference is entirely about where the key value originates and how visible it is at runtime.

import Pdffillr from '@pdffillr/sdk';

// Acceptable for local one-off scripts and automated tests.
// Do NOT use this pattern in long-lived production services.
const client = new Pdffillr({
  apiKey: 'my-pdffillr-api-key',
});

5. Managing Multiple Environments

Professional deployments use a separate API key for each environment - development, staging, and production at minimum. This limits the blast radius of a key leak: an exposed development key cannot be used to access production data, and revoking it does not disrupt live traffic. It also makes it straightforward to audit which environment made which API calls from the Pdffillr dashboard.

# .env.development
PDFFILLR_API_KEY=sk_dev_xxxxxxxxxxxxxxxx

# .env.production  (or set in your deployment platform's UI)
PDFFILLR_API_KEY=sk_prod_xxxxxxxxxxxxxxxx

// Load the correct .env file based on NODE_ENV
import * as dotenv from 'dotenv';

dotenv.config({
  path: `.env.${process.env.NODE_ENV ?? 'development'}`,
});

import Pdffillr from '@pdffillr/sdk';

const client = new Pdffillr({
  apiKey: process.env['PDFFILLR_API_KEY'],
});

6. Key Rotation

Key rotation is the process of replacing an active API key with a newly generated one. You should rotate keys on a regular schedule - quarterly for low-risk environments, immediately for any key that may have been compromised. Because the SDK reads the key from process.env, rotation is an infrastructure operation: no code changes are required in your application.

// Step 1 - generate the new key in the Pdffillr dashboard
// Step 2 - add the new key to your environment alongside the old one
//           (both keys are active during the transition window)
// Step 3 - deploy your application with the new key value
// Step 4 - revoke the old key from the dashboard once all
//           instances are running with the new key

// In your .env (during transition):
// PDFFILLR_API_KEY=sk_new_xxxxxxxxxxxxxxxx

// In your application code - no changes needed:
const client = new Pdffillr({
  apiKey: process.env['PDFFILLR_API_KEY'],
});

7. Security Checklist

Use this checklist to verify your authentication setup is production-ready before you deploy. Each item addresses a common misconfiguration that has led to real API key leaks in production systems.