Form invites (Mint)

An invite token is a shareable URL that grants anonymous access to a single published form. Any holder of the URL can load and submit the form — no login required. You control the lifetime, an optional submission cap, and whether the token remains active.

Tokens are managed from the Invite links panel inside the form builder (Admin → Forms → [form] → Invite links).

Requirements

• The form must be in published status before you can mint a token. Attempting to mint against a draft or archived form returns 409 with the message cannot mint invite tokens for a form in status '<status>'.
• The caller must hold the forms:admin scope and the forms.publish RBAC permission. Standard member tokens with forms:read can list tokens but cannot mint or revoke.

Endpoints

Mint a token

POST /api/v1/tenant/forms/definitions/:form_id/invites

Request body

Success response — 201 Created

{
  "id": "3f2e…",
  "tenant_id": "ten_…",
  "form_definition_id": "fd_…",
  "token": "a1b2c3d4-e5f6-…",
  "expires_at": "2026-06-16T12:00:00Z",
  "max_submissions": 100,
  "submission_count": 0,
  "created_at": "2026-05-16T12:00:00Z"
}

The token field is the raw UUID that makes up the share URL:

https://app.fastyoke.io/f/<token>

The token value is stored in the database only as a SHA-256 hash. If you lose the URL you must mint a new token — there is no way to retrieve the plaintext token after the 201 response.

List tokens for a form

GET /api/v1/tenant/forms/definitions/:form_id/invites?tenant_id=<tenant_id>

Returns all tokens for the form (active, expired, and exhausted), ordered by created_at descending. Requires the forms:read scope.

Success response — 200 OK

An array of objects with the same shape as the mint response. submission_count reflects the live counter — use it to track how many submissions a token has received.

Revoke a token

DELETE /api/v1/tenant/forms/invites/:invite_id?tenant_id=<tenant_id>

Deletes both the platform routing index and the tenant-side record. Any holder who attempts to load or submit the form via the revoked URL receives 410 Gone. Existing submissions are not deleted — revocation prevents future use only.

Requires the forms:admin scope and the forms.delete RBAC permission.

Success response — 200 OK

{ "revoked": true }

Public URL behaviour

When a visitor opens https://app.fastyoke.io/f/<token>:

The response body also includes a submissions_remaining field (integer or null for unlimited) so your frontend can display a "X responses remaining" notice if desired.

Submission atomicity

The submission counter is incremented atomically in the same UPDATE that enforces the cap. If the increment touches zero rows (cap already reached or token expired between the form load and the submit click), the submit returns 410 without writing a form_submissions row.

Tier limits

When the request violates a tier cap the backend returns:

HTTP 402 Payment Required
{
  "error": "tier_quota_exceeded",
  "tier": "hobby",
  "detail": {
    "feature": "forms_invite_long_lived",
    "limit_hours": 720,
    "requested_hours": 8760
  }
}

or, for the submissions dimension:

{
  "error": "tier_quota_exceeded",
  "tier": "hobby",
  "detail": {
    "feature": "forms_invite_unlimited_submissions",
    "limit": 500,
    "requested_max_submissions": null
  }
}

See Forms tier entitlements for the complete matrix.

Error reference