Authentication
How to authenticate with the Formfex Public API
Overview
The Formfex Public API uses API keys for authentication. Every request must include a valid API key in the Authorization header as a Bearer token.
Plan Requirement
API access requires a Starter plan or higher. Free plan users cannot create API keys.
API Key Format
API keys follow the format:
fxk_live_<keyId>.<secret>
| Component | Length | Description |
|---|---|---|
| Prefix | 9 chars | fxk_live_ — identifies the key type |
| Key ID | 12 hex chars | Random identifier for fast lookup and audit logs |
| Separator | 1 char | . |
| Secret | 64 hex chars | Cryptographic secret (256-bit random) |
Example:
fxk_live_a1b2c3d4e5f6.abcdef0123456789abcdef0123456789abcdef0123456789abcdef0123456789
Store Securely
The full API key is shown only once at creation time. Formfex stores only a SHA-256 hash — lost keys cannot be recovered, only rotated.
Making Requests
Include your API key in the Authorization header:
curl -X GET "https://api.formfex.com/api/v1/public/forms" \
-H "Authorization: Bearer $FORMFEX_API_KEY"All Public API endpoints are under the /api/v1/public/ base path.
Creating an API Key
Navigate to API Keys
Go to Settings → API Keys in the Formfex dashboard.
Create a new key
Click Create API Key, give it a name (e.g., "My Integration"), select the scopes you need, and optionally set an expiry date (up to 2 years).
Copy and store the key
Copy the full key immediately. It will not be shown again.
Scopes
Each API key has granular scopes that control which endpoints it can access. You must assign at least one scope when creating a key.
| Scope | Allows |
|---|---|
FORMS_READ | List and read forms |
FORMS_WRITE | Create, update, and delete forms |
RESPONSES_READ | Read form responses/submissions |
WEBHOOKS_READ | List webhooks |
WEBHOOKS_WRITE | Create, update, and delete webhooks |
AI_GENERATE | AI form generation and job status |
ANALYTICS_READ | Smart analytics read operations |
If a request requires a scope your key doesn't have, you'll receive a 403 Forbidden response:
Key Rotation
You can rotate an API key without downtime using the grace period mechanism:
Start rotation
Call the rotate endpoint or use the dashboard. A new key is generated with the same name and scopes.
Grace period
The old key remains valid during the grace period (default: 24 hours, max: 7 days). Both old and new keys work simultaneously.
Transition
Update your application to use the new key. Once the grace period expires, the old key is automatically deactivated.
Limits per Plan
| Plan | Max API Keys |
|---|---|
| Free | 0 (no API access) |
| Starter | 3 |
| Pro | 10 |
| Max | 25 |
Error Responses
| Status | Meaning |
|---|---|
401 Unauthorized | Missing, invalid, revoked, or expired API key |
403 Forbidden | Key lacks the required scope, or plan doesn't include API access |
429 Too Many Requests | Rate limit or monthly quota exceeded (see Rate Limits) |
Security Best Practices
- Never expose keys in client-side code — use server-to-server calls only
- Use the minimum scopes your integration needs
- Set an expiry date for keys used in temporary integrations
- Rotate keys regularly using the built-in rotation with grace period
- Revoke unused keys promptly from the dashboard