---
title: Flarum
---

# Flarum

Official CaptchaLa extension for Flarum. Adds CAPTCHA verification to the actions bots typically target on a forum — registration, login, password reset and posting — with per-action toggles in the admin panel.

## What it covers

Each action below is an individual toggle under `Admin → Extensions → CaptchaLa`.

- Registration
- Login
- Password reset
- Post replies
- New discussions
- Profile edits

Authenticated sessions opened via an SSO / Auth Sync provider are exempt — see [SSO / Auth Sync](#sso-auth-sync) below.

## Install

### 1. Require the extension

From your Flarum installation root:

```bash
composer require captchala/flarum
```

Alternatively, in `Admin → Extension Manager` paste `captchala/flarum` into the **Install** field. The extension targets Flarum ≥ 1.8 and PHP ≥ 8.1.

### 2. Enable in admin panel

Open `Admin → Extensions`, find **CaptchaLa**, and click **Enable**.

### 3. Configure

In the extension's settings panel:

1. Paste your **App Key** and **App Secret** from [`dash.captcha.la`](https://dash.captcha.la).
2. Toggle which actions to protect.
3. Save.

## Configuration

Settings are stored in the standard Flarum settings table under the `captchala.*` prefix.

| Setting | Type | Default | Description |
| --- | --- | --- | --- |
| App Key | string | — | Public key (`cl_pub_…`) from the CaptchaLa dashboard. Required. |
| App Secret | string | — | Server secret. Required. Used server-side only to call `/v1/validate`. |
| Protect registration | bool | `true` | Challenge on sign-up. |
| Protect login | bool | `false` | Challenge on the login modal. Off by default because most forums protect login via rate limiting. |
| Protect password reset | bool | `true` | Challenge when requesting a password-reset email. |
| Protect post replies | bool | `false` | Challenge when posting a reply. Off by default; enable if the forum is under spam pressure. |
| Protect new discussions | bool | `false` | Challenge when opening a discussion. |
| Verification mode | enum | `popup` | One of `popup`, `bind`, `embed`. Maps to the Web SDK `product` option. |
| Theme | enum | `auto` | `light`, `dark`, or `auto`. |
| Skip for trusted users | bool | `true` | Users in groups marked as trusted (e.g. moderators) bypass the challenge. |

## SSO / Auth Sync

The extension cooperates with Flarum's standard auth-provider hooks (`UserAuthenticated`, third-party Auth Sync providers, OAuth bridges).

- If the user arrives via an authenticated SSO session, no challenge is rendered — the extension treats the session as already verified.
- For mixed setups where some users sign in via SSO and others via the local form, only the local form path runs the challenge.
- The `skip_for_trusted_users` toggle stacks on top of this: trusted groups bypass the challenge even on a local-form login.

## FAQ

**Is the extension free?**

Yes. The Composer package is free. The CaptchaLa free plan covers 10,000 verifications a month.

**Does it stop spam sign-ups?**

It blocks or challenges most automated registrations at the first risk score. No CAPTCHA blocks 100% — but in our test forums, spam registration volume drops by roughly an order of magnitude after enabling.

**Can I require it only on registration?**

Yes. Each action is a separate toggle. The default profile enables registration and password reset only.

**Does it work with SSO / Auth Sync?**

Yes. Sessions opened by an SSO / Auth Sync provider skip the challenge. See [SSO / Auth Sync](#sso-auth-sync).

**Is it open source?**

Yes — the PHP extension code is open source. Verification calls are made against the hosted CaptchaLa service.

## Source

- Extension repository: [`github.com/Captcha-La/captchala-flarum`](https://github.com/Captcha-La/captchala-flarum)
- Packagist: [`captchala/flarum`](https://packagist.org/packages/captchala/flarum)
- Related: [Web SDK](/web-sdk) · [PHP Server SDK](/sdk/server-php) · [API Reference](/api-reference)