Welcome to the NZRT Wiki Podcast. Today we’re looking at Users and Groups.

We’re going to walk through how Flarum handles users, groups, permissions, and authentication. If you’ve ever wondered how the forum knows who you are, what you’re allowed to do, or how an automated script logs in and posts on your behalf, this episode covers all of that.

Let’s start with users. Every person on the forum is represented by a user object, and that object carries a set of fields that describe who they are and what they’ve been up to. There’s a unique integer ID that identifies the account internally, and a username which is the unique login name you use to sign in. There’s also a display name, which is what other people see in the interface — and if you don’t set one explicitly, it just defaults to your username. Your email address is stored too, though that’s only visible to admins. The system also tracks whether your email has been confirmed, when you first registered, and when you were last active on the forum. On top of that, it keeps a running count of how many discussions you’ve started and how many posts you’ve made. Finally, your user record has a relationship called groups, which links you to whichever groups you belong to — and that’s where permissions come from, as we’ll see in a moment.

Now let’s talk about built-in groups. Flarum ships with four groups already configured. The first is Admin, with an ID of one — this group has full access and all permissions across the board. The second is Guests, ID two — these are unauthenticated visitors, people browsing the forum without logging in. Third is Members, ID three — this covers all registered users, so anyone who has created an account automatically belongs to this group. And fourth is Moderators, ID four — moderators can edit or delete any post, lock threads, and sticky discussions. Beyond these four, you can create your own custom groups through Admin, then Groups in the control panel.

Speaking of permissions — in Flarum, permissions are assigned to groups, not to individual users. You manage this through Admin, then Permissions. There are several core permissions to know about. View forum controls whether a group can see discussions at all. Sign up controls whether visitors can register an account. Start discussions lets a group create new threads. Reply to discussions lets them post in existing ones. Use markdown gives a group the ability to format their posts. Edit own posts lets someone modify a post they’ve already made, and Delete own posts lets them remove it entirely. Moderators and admins automatically have elevated access beyond what this list covers, so they don’t need each of these switched on individually.

Now let’s move on to authentication, which is where things get a little more technical — but don’t worry, we’ll keep it simple. Flarum supports three ways of logging in. The default method is a plain username and password. You can also enable OAuth through extensions, which lets users sign in with accounts from places like GitHub, Google, or Facebook. And finally, there are API tokens, which are used for programmatic access — meaning when a script or an agent needs to interact with the forum on someone’s behalf.

Here’s how API token authentication works in practice. When you make an HTTP request to the forum’s API, you include an Authorization header, and you set its value to the word Token followed by a space and then the token string itself. You can generate tokens inside user settings, or you can create one by making a POST request to the API token endpoint.

There’s an important gotcha here that’s worth paying attention to. Pre-generated tokens — the kind you copy out of the settings page — work fine for read-only requests like fetching a list of discussions. But if you try to use one to create a post, update something, or delete something, it will fail. That’s because write operations go through CSRF validation, which those static tokens don’t satisfy. For any write operation, you need a session token instead, and you get that by making a POST request to the token endpoint with actual login credentials. That session token is what you use for mutations. If you’re building any kind of automation that posts to the forum, this is the distinction you need to get right.

So to bring it all together: users are identified by a handful of fields including their ID, username, and group memberships. Groups are the unit of control — four built-in ones cover admins, guests, members, and moderators, and you can add your own. Permissions are set on groups rather than individuals, covering everything from viewing the forum to deleting your own posts. And authentication can happen via password, OAuth, or API token — with the key rule that session tokens from a fresh login are required for any write operation through the API.

That’s it for this episode of the NZRT Wiki Podcast. Thanks for listening.