Authentication
Conversion APIs, PDF APIs, and async task APIs require an API key. The health status API is public. Dashboard-only APIs are not described in this reference.
Get the API Key
| Method | Description |
|---|---|
Configure API_KEY | Set API_KEY in .env before startup. During database initialization, the ComPDF Self-hosted hashes this value and stores it in the api_keys table. Clients send the plaintext value as x-api-key. |
| First-boot generated key | If API_KEY is empty and no active key exists, the initialization script generates a random API key and prints it once in the startup logs. |
| Dashboard | Open /admin and use the API Management page to view the API Access Key for the deployment. |
The plaintext key generated on first boot is also stored at STORAGE_DIR/.api-key-plaintext so the ComPDF Web can automatically attach x-api-key. Treat this file as a secret.
Use the API Key
bash
curl -X POST "http://localhost:8080/api/v1/process/pdf/docx" \
-H "x-api-key: your_api_key_here" \
-F "[email protected]"If the key is missing, invalid, or revoked, the ComPDF Self-hosted returns 401 UNAUTHORIZED.