User Registration

You can extend form submissions to create user accounts on your site. When a form's _name matches a configured role, the platform runs a registration workflow instead of a simple submission.

Prerequisites

Registration requires two entries in your site's _admin.yml:

  1. A role defining the permission level
  2. A form linking a form name to that role

Configuration

Defining Roles

Add a roles list to _admin.yml:

roles:
  - name: member
    email_confirmation: true
    admin_approval: false

Role options:

  • name — Role identifier. This is assigned to the user when registration completes.
  • email_confirmation — If true, the user must confirm their email before the account is created. A confirmation link is sent (expires after 24 hours).
  • admin_approval — If true, a site admin must approve the submission before the account is created. Admins receive an email notification.

Both options can be combined for a two-step verification: email confirmation first, then admin approval.

Linking Forms to Roles

Add a forms list to _admin.yml:

forms:
  - name: signup
    role: member
  • name — Must match the _name config field in your HTML form.
  • role — Must match a role name from the roles list.

Full Example

roles:
  - name: member
    email_confirmation: true
    admin_approval: false

  - name: contributor
    email_confirmation: true
    admin_approval: true

forms:
  - name: signup
    role: member

  - name: apply
    role: contributor

HTML Form

Build the form using the standard form submission pattern. The _name must match a configured form name:

<form action="/app/forms/submit" method="POST">
  <input type="hidden" name="_name" value="signup">
  <input type="hidden" name="_return_url" value="/">

  <input type="text" name="first_name" placeholder="First name" required>
  <input type="text" name="last_name" placeholder="Last name" required>
  <input type="email" name="email" placeholder="Email" required>
  <input type="tel" name="phone" placeholder="Phone">
  <input type="text" name="city" placeholder="City">
  <input type="text" name="state" placeholder="State">

  <button type="submit">Sign Up</button>
</form>

Recognized Fields

The following field names are mapped to the user profile when the account is created:

  • email — Required. Used for login and email confirmation.
  • username — Optional. Auto-generated from email if not provided.
  • first_name, last_name — Display name fields.
  • phone, city, state, bio — Profile fields.

Any other fields are stored in the submission data but not mapped to the user profile.

Registration Flow

The exact flow depends on the role configuration:

No verification (email_confirmation: false, admin_approval: false)

  1. User submits form → Cap.js challenge
  2. Account created immediately
  3. User sees a welcome page with a sign-in link

Email confirmation only (email_confirmation: true)

  1. User submits form → Cap.js challenge
  2. User sees "Check your email" page
  3. User clicks confirmation link in email (expires in 24 hours)
  4. Account created → welcome page

Admin approval only (admin_approval: true)

  1. User submits form → Cap.js challenge
  2. User sees "Application pending approval" page
  3. Site admins receive an email notification
  4. Admin approves or rejects in the dashboard
  5. If approved: account created, user receives welcome email
  6. If rejected: user receives a rejection email

Both (email_confirmation: true, admin_approval: true)

  1. User submits form → Cap.js challenge
  2. Email confirmation step (as above)
  3. After email confirmed → admin approval step (as above)

Registration Statuses

Each registration submission has a status visible in the dashboard:

  • Pending email confirmation — Waiting for user to click the confirmation link
  • Pending admin review — Waiting for an admin to approve or reject
  • Approved — Admin approved, but account not yet created (edge case)
  • Registered — Account created successfully
  • Rejected — Admin rejected the submission

Troubleshooting

"No role found" error

The form's _name value doesn't match any entry in the forms list in _admin.yml, or the linked role doesn't exist in the roles list.

Confirmation links expire after 24 hours. The user needs to resubmit the form.

User already exists

If a user with the same email already exists, the platform reuses the existing account and adds the role assignment. No duplicate user is created.