API Key Management
API keys are how your application authenticates with the Qpher API. Every request to
Qpher must include a valid API key in the x-api-key header.
Your API key is displayed only once at creation time. Copy it immediately and store it securely. Qpher stores only a hash of the key and cannot retrieve the original value.
Creating an API Key
You can create API keys from the Dashboard at portal.qpher.ai or through the API.
From the Dashboard
- Navigate to Settings > API Keys.
- Click Create API Key.
- Give the key a descriptive name (for example, "Production Backend").
- Copy the key immediately -- it will not be shown again.
Per-Plan Limits
Each plan has a maximum number of active API keys:
| Plan | Max Active API Keys |
|---|---|
| Free | 1 |
| Starter | 3 |
| Growth | 5 |
| Pro | 10 |
| Enterprise | Unlimited |
If you have reached your plan's limit, you must revoke an existing key before creating a new one, or upgrade your plan.
Using Your API Key
Include the API key in every request using the x-api-key header:
curl -X POST https://api.qpher.ai/api/v1/kem/encrypt \
-H "Content-Type: application/json" \
-H "x-api-key: qph_your_api_key_here" \
-d '{"plaintext": "SGVsbG8gV29ybGQ=", "key_version": 1}'Rotating an API Key
Key rotation follows a create-new-then-revoke-old pattern. This ensures zero downtime during rotation -- the old key remains valid briefly while you update your application to use the new key.
How Rotation Works
- You request rotation through the API or Dashboard.
- Qpher generates a new API key with an incremented version number.
- The old key is revoked immediately.
- The new key is returned to you (shown once).
- Update your application to use the new key.
curl -X POST https://api.qpher.ai/api/v1/tenants/{tenant_id}/api-keys/rotate \
-H "Content-Type: application/json" \
-H "x-api-key: qph_your_current_key"Key rotation requires a Starter plan or above. Free plan users have a single API key that cannot be rotated.
When to Rotate
Rotate your API keys when:
- A team member with key access leaves your organization.
- You suspect a key may have been exposed (in logs, source code, or a public repository).
- Your security policy requires periodic rotation (for example, every 90 days).
- You are preparing for a compliance audit.
Revoking an API Key
If an API key is compromised, revoke it immediately:
- Navigate to Settings > API Keys in the Dashboard.
- Find the compromised key and click Revoke.
- The key becomes invalid instantly. Any request using the revoked key receives
401.
After revocation, create a new key and update your application.
If you believe your API key has been compromised, revoke it immediately. Do not wait for a scheduled rotation. Requests made with a revoked key are rejected instantly.
Version Tracking
Every API key has a version number that increments with each rotation. This version is
included in audit logs and the X-API-Key-Version header on every request, so you can
trace exactly which key was used for any operation.
| Key Event | Version |
|---|---|
| First key created | 1 |
| Key rotated | 2 |
| Key rotated again | 3 |
All versions (active and revoked) are retained in the audit trail. Revoked keys are never deleted from the system -- they remain as historical records.
Security Best Practices
- Never hardcode API keys in your source code. Use environment variables or a secrets manager.
- Rotate regularly -- at least every 90 days for production keys.
- Use separate keys for development and production environments.
- Monitor usage in the Dashboard to detect unusual activity.
- Revoke immediately if a key is compromised or a team member leaves.