API Keys Management

Programmatically manage API keys for your VeilForms account. Create keys with specific permissions, list existing keys, and revoke keys when needed.

List API Keys

Example Request:

curl https://veilforms.com/api/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "keys": [
    {
      "id": "a1b2c3d4e5f6...",
      "name": "Production Server",
      "prefix": "vf_abc1...",
      "permissions": ["forms:read", "submissions:read"],
      "createdAt": "2024-01-15T10:30:00Z",
      "lastUsed": "2024-01-20T14:22:00Z"
    },
    {
      "id": "x9y8z7w6v5u4...",
      "name": "Analytics Integration",
      "prefix": "vf_xyz9...",
      "permissions": ["submissions:read"],
      "createdAt": "2024-01-10T08:00:00Z",
      "lastUsed": null
    }
  ],
  "total": 2
}

Create API Key

Request Body:

{
  "name": "My API Key",
  "permissions": ["forms:read", "submissions:read"]
}

Parameters:

FieldTypeRequiredDescription
namestringYesDisplay name for the key (max 50 chars)
permissionsarrayNoPermissions to grant (default: all permissions)

Valid Permissions:

PermissionDescription
forms:readList and view form configurations
forms:writeCreate, update, delete forms
submissions:readList and fetch submissions (encrypted)
submissions:deleteDelete submissions

Example Request:

curl -X POST https://veilforms.com/api/api-keys \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Server",
    "permissions": ["forms:read", "submissions:read"]
  }'

Response:

{
  "key": {
    "id": "a1b2c3d4e5f6...",
    "name": "Production Server",
    "key": "vf_abc123xyz789...",
    "permissions": ["forms:read", "submissions:read"],
    "createdAt": "2024-01-15T10:30:00Z"
  },
  "warning": "Save this API key now! This is the only time it will be shown. We cannot recover it."
}

Revoke API Key

Path Parameters:

ParameterDescription
keyIdThe ID of the API key to revoke (returned when the key was created)

Example Request:

curl -X DELETE https://veilforms.com/api/api-keys/a1b2c3d4e5f6 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response:

{
  "success": true,
  "revoked": "a1b2c3d4e5f6..."
}

Limits

PlanMax API Keys
Free5
Starter10
Pro25
EnterpriseUnlimited

Error Responses

400 Bad Request

{
  "error": "Key name is required"
}

{
  "error": "Invalid permission: invalid:permission"
}

{
  "error": "Maximum number of API keys reached (5). Delete an existing key first."
}

401 Unauthorized

{
  "error": "Invalid or missing authentication"
}

403 Forbidden

{
  "error": "Access denied"
}

Returned when attempting to revoke a key that belongs to another user.

404 Not Found

{
  "error": "API key not found"
}

429 Too Many Requests

{
  "error": "Too many requests. Please try again later.",
  "retryAfter": 60
}

Rate limit: 20 requests per minute.

Security Best Practices

  1. Use scoped permissions - Only grant the permissions your integration needs
  2. Create separate keys - Use different keys for different integrations
  3. Rotate keys regularly - Delete and recreate keys periodically
  4. Monitor usage - Check the lastUsed timestamp in the key list
  5. Store securely - Use environment variables or a secrets manager

Example: Creating a Read-Only Key

const response = await fetch('https://veilforms.com/api/api-keys', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_JWT_TOKEN',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Read-Only Analytics',
    permissions: ['forms:read', 'submissions:read']
  })
});

const { key, warning } = await response.json();

// Store key.key securely - it won't be shown again!
console.log('New API Key:', key.key);
console.log('Warning:', warning);

Next Steps