Authentication

The RizzForms API supports two authentication methods: Bearer API keys for programmatic access and session cookies for the browser dashboard. Public ingestion endpoints (/f/ and /json/) do not require authentication.

Overview

There is no API endpoint for creating accounts or generating API keys. Users sign up through the web form at forms.rizzness.com (protected by Turnstile CAPTCHA and email confirmation), then create API keys from the dashboard.

API Keys

API keys are created and managed from your account dashboard under Settings → API Keys. Each key is prefixed with frk_ so you can identify RizzForms credentials at a glance.

frk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Keys are shown in full only once at creation time. Store them securely. If a key is compromised, revoke it from the dashboard and create a new one.

Bearer Token

Pass your API key in the Authorization header using the Bearer scheme:

Authorization: Bearer frk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

Example: List your forms

curl -s https://www.rizzness.com/api/forms \
  -H "Authorization: Bearer frk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"

Example: Create a form

curl -s -X POST https://www.rizzness.com/api/forms \
  -H "Authorization: Bearer frk_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
  -H "Content-Type: application/json" \
  -d '{"name": "Contact Form"}'

Permissions & Roles

Each API key carries a set of permission scopes that control what it can access. There are three scopes:

Scope	Grants access to
`can_create_forms`	Create and update forms, manage plugins, rotate secrets
`can_read_submissions`	Read non-spam submissions
`can_read_spam_submissions`	Read spam submissions

For convenience, the dashboard offers two preset roles:

Role	Scopes
Admin	`can_create_forms`, `can_read_submissions`, `can_read_spam_submissions`
Readonly	`can_read_submissions`

Choose the Readonly role when you only need to pull submission data (for example, syncing to a CRM). Use Admin when your integration also creates forms or manages webhooks.

Session Authentication

When you are signed in to the RizzForms dashboard, your browser session cookie authenticates API requests automatically. This is how the dashboard itself works. Session auth provides access to all endpoints, including the /api/stats endpoint which is session-only.

Error Responses

Authentication failures return standard JSON error objects:

401 Unauthorized — missing or invalid key

{
  "ok": false,
  "error": "unauthorized",
  "message": "No API key provided. Include an Authorization: Bearer header."
}

{
  "ok": false,
  "error": "invalid_api_key",
  "message": "The provided API key does not match any active key."
}

403 Forbidden — insufficient permissions

{
  "ok": false,
  "error": "forbidden",
  "message": "Your API key does not have the required permission for this action."
}

See Error Codes for the full list of error responses.