Authentication & Verification Keys - CodeFreeForm API Documentation

Overview

The Contact Form API uses a verification key system for authentication. Each key is associated with an email address and can optionally be restricted to specific domains.

Why verification keys? They provide a simple, secure way to authenticate without complex OAuth flows or API tokens.

Obtaining a Verification Key

To get a new verification key, send a POST request to the home endpoint:

Endpoint: POST /

curl -X POST https://codefreeform.com/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "requestType": "generateKey"
  }'

Request Parameters:

Parameter	Required	Description
`email`	Yes	Your email address where the key will be sent
`requestType`	No	Set to "generateKey" (default) to create a new key

Response:

{
  "success": true,
  "message": "New key generated and sent to your-email@example.com.",
  "key": "ABC123",
  "keys_count": 1
}

The verification key will also be sent to your email address.

Retrieving Existing Keys

If you've lost your keys or want to retrieve all active keys for your email:

curl -X POST https://codefreeform.com/ \
  -H "Content-Type: application/json" \
  -d '{
    "email": "your-email@example.com",
    "requestType": "getKeys"
  }'

Response:

{
  "success": true,
  "message": "All keys have been emailed to your-email@example.com.",
  "keys_count": 3
}

All your active verification keys will be sent to your email.

Key Limits

Key Restrictions

Maximum keys: 10 active keys per email address
Deleted keys: Don't count toward the limit
Status types: Keys can be "active" or "disabled"
Only active keys: Can be used for API requests

If you try to create more than 10 keys:

{
  "error": "You have reached the maximum of 10 active keys."
}

Domain Restrictions

Keys can optionally be restricted to specific domains for added security. When a key has use_domain enabled, requests from other domains will be rejected.

Domain Mismatch Error: If you try to use a domain-restricted key from a different domain, you'll receive a 400 error.

Error Response:

{
  "success": false,
  "message": "Verification key domain mismatch.",
  "errors": {
    "access_key": ["Verification key domain mismatch."],
    "__all__": ["Domain does not match."]
  }
}

Best Practice

Use domain restrictions if your key will only be used from specific domains (e.g., your production website). This prevents unauthorized use of your key from other websites.

Using Your Verification Key

Include your verification key in every API request using the access_key parameter:

const formData = {
  access_key: 'ABC123',  // Your verification key
  email: 'sender@example.com',
  message: 'Hello!',
  subject: 'Contact Form'
};

const response = await fetch('/api/contact-api/', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify(formData)
});

Security Warning: Never expose your verification key in public repositories or client-side code for production use. Consider using server-side proxy endpoints or environment variables.