API Keys
Every render request is authenticated with an API key. Keys are created in the dashboard, scoped to a single workspace, and sent as a bearer token. This page covers creating, identifying, rotating, and revoking them.
How keys authenticate requests
BladePDF authenticates the HTTP API with a bearer token. The Laravel package reads your key from config('bladepdf.api_key') (the BLADEPDF_API_KEY environment variable) and sends it on every call as an Authorization: Bearer header — you never build the header yourself.
1Authorization: Bearer blpdf_xxxxxxxxxxxxxxxxxxxxxxxxA key resolves to exactly one workspace. All renders made with it count toward that workspace's plan limits, usage, and billing.
Create a key
- Open API Keys in the BladePDF dashboard.
- Choose Create key and give it a descriptive name (for example,
production-apiorstaging). - Optionally add a description, tags, and an expiry date.
- Copy the full key from the confirmation dialog and store it in your secrets manager.
The complete key value is only displayed when it is created. BladePDF stores a hash, not the key itself, so it cannot show it again. If you lose it, create a new key and revoke the old one.
Key format and identification
Keys are issued with a blpdf_ prefix. After creation, a key is identified in the dashboard by its prefix and last six characters (its suffix) — enough to recognize it without exposing the secret.
| Field | Example | Notes |
|---|---|---|
| Full key | blpdf_9f2c…a71b3e |
Shown once at creation. Use this value in BLADEPDF_API_KEY. |
| Prefix | blpdf_ |
Constant across all keys. |
| Suffix | a71b3e |
Last six characters, shown in the dashboard for identification. |
Name, describe, and tag keys
Give each environment or integration its own key. A name, an optional description, and tags make it easy to tell keys apart, audit them, and revoke exactly the one you need. A common pattern is one key per environment (production, staging, local) and one per external integration.
Expiry
A key can be given an expiry date when it is created. After that date it stops authenticating and requests made with it are rejected. Leave the expiry blank for a long-lived key, or set one for temporary access such as a contractor or a short-lived integration.
Usage tracking
Each key records its own activity so you can spot unused or unexpectedly busy keys:
- Total requests and requests in the last 24 hours, with a short usage sparkline.
- Last used timestamp, IP address, and user agent.
- Current status: active, revoked, or expired.
Rotate a key
Rotating replaces a key without downtime when you deploy the new value alongside the old one:
- Create a new key.
- Deploy it to
BLADEPDF_API_KEYin the relevant environment. - Confirm renders succeed with the new key (check its usage count in the dashboard).
- Revoke the old key.
Rotate immediately if a key is ever committed to source control, printed in logs, or otherwise exposed.
Revoke keys
Revoking a key takes effect immediately — in-flight and future requests using it are rejected. You can revoke a single key, or use Revoke all to invalidate every key in the workspace at once (useful during an incident). The API keys list can also be exported to CSV for auditing.
Use the key in Laravel
Place the key in your environment file. The package picks it up automatically.
1BLADEPDF_API_KEY=blpdf_xxxxxxxxxxxxxxxxxxxxxxxxTo use the same key from another language or a raw HTTP client, see the REST API reference.
Treat keys like passwords. Only call BladePDF from trusted backend code. Never ship a key in browser JavaScript, a mobile app, a public repository, screenshots, or logs. Store it in environment variables or a secrets manager, and rotate on any suspected exposure.