Guide
Rotate API keys safely and recover quickly when secrets are lost or exposed
Use this guide when you need more than one lifecycle call. The examples move from the smallest safe cutover to a realistic staged rollout and then to a compromise-response path with validation and rollback checkpoints.
Recommended path
- Start with the smallest safe rotation path for one integration.
- Move to overlapping-key rollout when you need environment-by-environment promotion.
- Use the compromise path when containment speed matters more than rollout convenience.
Management auth
Key lifecycle routes use bearer auth because keys belong to the signed-in account.
Runtime auth
Validation happens on real rendering routes that send the replacement secret in X-API-Key.
Guide spectrum
This page shows one easiest path, one realistic path, and one advanced path.
Before You Begin
Confirm secret storage, rollout ownership, and telemetry access first
Runbook quality comes from knowing who can change credentials, who can validate the cutover, and where the success signals will come from.
01
Secret manager ready
New key material is visible only on create and rotate responses, so you need a write target before you request it.
02
Cutover owner identified
Assign one owner who can update deployment config, run the smoke test, and stop the rollout if validation fails.
03
Telemetry access confirmed
Use /user/api-keys, /user/request-logs, and /user/usage as the validation surface before and after cutover.
Easiest Path
Rotate one active key, capture the replacement, and validate immediately
Use this path when one integration needs one replacement key now. It is also the right path when your plan does not leave room for an overlapping active key. Rotation revokes the previous key immediately, so only use it when you can cut over without waiting on a long multi-environment rollout.
curl "https://api.solidrelay.io/user/api-keys?status=active&mode=live&sort=last_used_desc" \
-H "Authorization: Bearer ACCESS_TOKEN"{
"total": 1,
"limit": 20,
"offset": 0,
"keys": [
{
"id": "00000000-0000-4000-8000-000000000001",
"name": "Production renderer",
"prefix": "sk_live_abcd1234",
"mode": "live",
"status": "active",
"createdAt": "2026-04-01T18:25:43.511Z",
"lastUsedAt": "2026-04-09T13:42:11.004Z",
"lastUsedIp": "203.0.113.10",
"lastUsedGeo": "New York, New York, US",
"revokedAt": null,
"allowedIps": ["203.0.113.10"]
}
]
}curl -X POST "https://api.solidrelay.io/user/api-keys/00000000-0000-4000-8000-000000000001/rotate" \
-H "Authorization: Bearer ACCESS_TOKEN"{
"id": "00000000-0000-4000-8000-000000000041",
"apiKey": "sk_live_newxxxxxxxxxxxxxxxx",
"prefix": "sk_live_7f3a",
"mode": "live"
}curl -X POST "https://api.solidrelay.io/v1/pdf" \
-H "X-API-Key: sk_live_newxxxxxxxxxxxxxxxx" \
-H "Idempotency-Key: rotation-smoke-2026-04-10" \
-H "Content-Type: application/json" \
-d '{
"html": "<h1>Rotation smoke test</h1><p>prod-us-east-1</p>",
"output": "url",
"filename": "rotation-smoke.pdf"
}'Why this path is safe
Single cutover
low coordination
You replace one secret, validate one environment, and finish without carrying two active keys for long.
Works under tight plan caps
free and low-overlap accounts
Create can fail when your plan has no spare active-key capacity, but rotate can replace the current key inside the existing limit.
Rollback boundary
before rotate only
After rotation, the previous key is already revoked. If the new secret is lost or misconfigured, rotate or create again instead of searching for the old full value.
Realistic Path
Create an overlapping key, promote by environment, then revoke the old key
This is the path most production teams will prefer when their plan leaves room for one more active key. It lets you validate the replacement in development, staging, and production before you retire the old prefix.
curl -X POST "https://api.solidrelay.io/user/api-keys" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "Production renderer rollout 2026-04",
"mode": "live",
"allowedIps": ["203.0.113.10", "198.51.100.24"]
}'{
"id": "00000000-0000-4000-8000-000000000052",
"apiKey": "sk_live_overlapxxxxxxxxxxxx",
"prefix": "sk_live_9c21",
"mode": "live"
}01
Write the new secret to your manager first
Persist the returned secret before any deploy so you do not lose the only copy.
02
Promote one environment at a time
Update development, then staging, then production. Run one smoke render in each environment before you continue.
03
Confirm the new prefix is actually serving traffic
Use request logs and usage breakdown to confirm successful requests are moving to the new key before you revoke the old one.
04
Revoke the previous key only after adoption is clean
Once all required environments are green, revoke the old key and keep the new prefix in your change record.
curl "https://api.solidrelay.io/user/request-logs?period=1d&limit=10&sort=created_desc&apiKeyId=00000000-0000-4000-8000-000000000052" \
-H "Authorization: Bearer ACCESS_TOKEN"{
"total": 6,
"limit": 10,
"offset": 0,
"endpointOptions": ["/v1/pdf", "/v1/pdf/jobs/job_01JX8V4Q8S9R6Z0ABCDE12345/file"],
"summary": {
"successCount": 6,
"failedCount": 0
},
"logs": [
{
"id": "00000000-0000-4000-8000-000000000901",
"apiKeyId": "00000000-0000-4000-8000-000000000052",
"apiKeyPrefix": "sk_live_9c21",
"endpoint": "/v1/pdf",
"ipAddress": "203.0.113.10",
"status": "success",
"errorReason": null,
"createdAt": "2026-04-10T13:42:11.004Z"
}
],
"canRevealIp": true
}curl -X DELETE "https://api.solidrelay.io/user/api-keys/00000000-0000-4000-8000-000000000001" \
-H "Authorization: Bearer ACCESS_TOKEN"Advanced Path
Contain a suspected exposure, preserve service, and rebuild the timeline
Use this path when a key may be exposed in logs, screenshots, source control, or a partner system. The goal is not just replacement. It is fast containment with enough evidence to understand what happened and whether any systems still depend on the compromised secret.
01
Choose the containment shape first
If your plan has spare active-key capacity, create an overlapping replacement and cut over critical services. If it does not, rotate immediately and treat the response secret as the emergency replacement.
02
Validate essential production traffic before final revoke
Smoke-test your critical render paths, then confirm the new prefix is showing successful requests in request logs.
03
Revoke the exposed key and review the surrounding activity window
Use usage summary, request logs, and key metadata to understand how much traffic moved, where failures occurred, and whether suspicious access continued after containment.
curl "https://api.solidrelay.io/user/usage?period=7d&includeBreakdown=true" \
-H "Authorization: Bearer ACCESS_TOKEN"{
"plan": "professional",
"totalRequests": 412,
"successCount": 404,
"failedCount": 8,
"errorsByCategory": {
"validation": 2,
"render": 5,
"timeout": 1
},
"remaining": 7588,
"requestsPerMinute": 120,
"concurrentRenders": 10,
"resetDate": "2026-04-28",
"keyBreakdown": [
{
"apiKeyId": "00000000-0000-4000-8000-000000000052",
"totalRequests": 87,
"failedCount": 0
}
]
}Advanced decision points
Overlap available
prefer create then revoke
This keeps rollback open while you update each environment and verify the new prefix is healthy.
No overlap available
rotate immediately
This closes the compromised key faster, but it also means rollback requires a fresh create or another rotate instead of restoring the old secret.
Investigation scope
metadata plus traffic history
Use key prefixes, last-used metadata, request-log outcomes, and usage breakdown to rebuild the incident window without needing unsupported internal telemetry.
Validation Checkpoints
Use API and telemetry feedback as the go or stop signals
A key change is complete only when the operational checks agree. These checkpoints keep the guide grounded in supported routes instead of hidden internals.
Capture checkpoint
POST /user/api-keys or POST /user/api-keys/:id/rotate
Create and rotate return the full secret once. If you lose it, create or rotate again. Do not expect list routes to recover it later.
Inventory checkpoint
GET /user/api-keys
Confirm prefix, status, allowlist, and last-used fields for both the retiring and replacement keys.
Traffic checkpoint
GET /user/request-logs
Look for successful requests on the new prefix. On Professional and Business plans you can also reveal IP addresses to confirm the expected egress source.
Quota checkpoint
GET /user/usage
Confirm the new key is consuming traffic without creating new auth, validation, or render failures.
Rollback checkpoint
depends on overlap
If the old key is still active, restore the previous secret and stop the rollout. If you already rotated, rollback means issuing a fresh replacement and repeating the cutover cleanly.
Common Failure Checks
Handle the predictable lifecycle mistakes directly
- No spare active-key capacity: use the rotate path or revoke a stale active key before trying to stage overlap.
- Secret was not stored at create or rotate time: issue a fresh create or rotate and restart from the secret-manager write step.
- New key works in staging but fails in production: compare secret-manager values, environment mapping, and
allowedIpsbefore retrying traffic. - Traffic still appears on the old prefix: stop the revoke step and keep tracing request logs until the remaining dependent system is updated.
- Compromise scope is unclear: prioritize containment first, then use request logs and usage data to rebuild the timeline.
Next Steps
Use canonical references for contracts, failures, and traffic validation
Reference
API keys
Use the create, list, rotate, update, and revoke contracts when implementing the lifecycle steps in this guide.
Telemetry
Usage and request logs
Validate cutover, review request history, and confirm batch or render health after a credential change.
Failure model
Errors and limits
Use shared auth, retryability, and limit behavior when a rotation exposes broader integration issues.
Operational maturity
Production hardening
Connect key hygiene to bounded retries, quota posture, monitoring, and release gates.