Forms server

This page covers what happens on the server when someone submits a form, and what you can configure there: access, rate limits, secrets, seeding, staff access and MCP tools. It is for app developers and module authors. Set up the module first: Overview.

Submit a form

POST /api/forms/:slug/submit takes JSON { answers, locale }. With files, send multipart/form-data instead: an answers JSON part, a locale part and one file:<key> part per file. locale is a language tag such as en or da-DK, and defaults to en.

The answer is { ok: true, id }. id is null when the form has storage: 'none'. Build the path with formsApi from @frigear-nu/forms/api:

import { formsApi } from '@frigear-nu/forms/api'

try {
  await $fetch(formsApi.submit('contact'), { method: 'POST', body: { answers, locale: 'en' } })
}
catch (error) {
  // 400: one issue per rejected field
  const issues = (error as { data?: { data?: { issues?: { path: (string | number)[], message: string }[] } } }).data?.data?.issues ?? []
}

Every error has its message in statusMessage and a snake_case code in data.code.

GET /api/forms/:slug returns the published definition without delivery, so recipients are never public.

Decide who may submit

A form's access.auth decides who may read and submit it. Its secrets are never part of the definition.

• Form access tokens start with ffk_. Staff create them per form in the admin area, and each is shown once. Only a SHA-256 hash is stored, with a display prefix, lastUsedAt and revokedAt.
• The password is stored as a scrypt hash. A form with auth: 'password' and no password set stays closed.
• availability: 'api' only removes the public page. The API still serves the form.

Rate limiting

Submissions are counted per client IP and form in key-value storage, in a fixed window: settings.rateLimit per settings.rateLimitWindowSeconds. Over the limit the answer is 429 with Retry-After. Wrong password attempts have their own counter, with the same limit and window.

The count is read and then written, so it is not exact under concurrency. That is enough against casual abuse.

Per-form secrets

Some secrets belong to one form, such as its own captcha secret key. They live in the form_secrets table, encrypted on the server with AES-256-GCM. They never end up in definition versions, submission snapshots, deliveries, imports or the public API. Staff can write them, but nobody can read them back.

The allowed keys are captcha.turnstile.secretKey, captcha.recaptcha.secretKey and captcha.hcaptcha.secretKey.

Seeding and import

Forms never inserts anything by itself. There are two ways to load definitions, and both insert only slugs that do not exist yet. Neither overwrites a form.

• Seed. seed: { enabled: true, forms: [...] } inserts at startup. Build a form shows it.
• Import. The Import JSON button in the admin area calls POST /api/admin/forms/import with { forms: [{ slug, name, definition }] }. It answers { inserted, skipped }.

Let staff manage forms

Every staff route calls authorize(event, permission) from Authorization: forms:manage for most routes, and forms:credentials for form access tokens, passwords and secrets. Who holds them is a matter of roles, as in Quick setup.

A route that loads a form authorizes twice. The first call fails with 401 or 403 before anything is looked up. The second call passes the record, so a policy can refine the answer:

export default defineEventHandler(async (event) => {
  await authorize(event, 'forms:manage')           // 401 or 403 before any 404
  const { id } = await getValidatedRouterParams(event, idParams().parse)
  const form = await loadForm(id)                  // then 404
  if (!form) throw notFound('Form not found.')
  await authorize(event, 'forms:manage', form)     // record-level policies
  // ...
})

Changing form access tokens, password or secrets needs forms:credentials, which is session only: a token gets 403 session_required, whatever its scopes.

Permissions and scopes

The named scope forms expands to forms:submit. The full table, with defaults, is under Permissions.

MCP tools

With settings.mcp: true, Forms adds these tools to the MCP endpoint.

submit-form always submits as the caller, and refuses forms that need a form access token or a password.

Next steps

• Reference – every route, and the forms:submitted hook for your own delivery.
• App – show a form, or its password gate, on any page.
• MCP – how agents connect and which permissions they hold.