Skip to content

Authentication⚓︎

This guide covers details about authenticating (logging in to FreeFlarum settings) via FreeFlarum's API, not Flarum.

There is also FreeFlarum Python Package, should you be interested in that.

Forgot password?⚓︎

FreeFlarum's login form expects the same password hash as is your forum admin account's password. This means that if you forgot your password, you may reset it at your forum:

  1. Ensure that you are logged out (you can use incognito/private browsing);
  2. Click on the "Log In" button at your Flarum forum;
  3. Click on the "Forgot password?" link in the bottom of the modal;
  4. Input your admin's E-mail address;
  5. Follow the instructions that were sent to that E-mail address and reset your password;
  6. You may now use this new password to log in to FreeFlarum.

Access tokens⚓︎

If you had the chance to look at your account settings at FreeFlarum, you might've already noticed that there is a section where all of your access tokens are listed.

Access tokens are created on every successful login to your FreeFlarum forum account. They can be used by outside parties to perform actions on behalf of your account (e. g.: download your forum data, link your domain, fixup your forum, get your forum information, etc...).

The main idea is that you may provide third party migration services with one of your access tokens, and they can fetch your forum data and migrate your forum for you. Or, you might simply want to create a personal script to link your domain under certain conditions, for example.

All API routes are listed at https://api.freeflarum.com/.

Access tokens with "elevated permissions"⚓︎

Access tokens that have "elevated permissions" are created only when you log in to FreeFlarum via its main website (https://freeflarum.com). Any logins/access tokens created outside of the main page will not have elevated permissions.

Table of permissions for access tokens⚓︎

Can Normal token Token with elevated permissions
Fetch forum information (tag, E-mail, etc...) ✅ ✅
Fetch FoF Uploads limit ✅ ✅
Fixup forum ✅ ✅
Link custom domain ✅ ✅
Fetch (available) server logs ✅ ✅
Export your forum data (also to CSV) ✅ ✅
Revoke other access tokens ❌ ✅
Remove your forum ❌ ✅

For security reasons, you may remove your forums and revoke other access tokens only if you log in via the main FreeFlarum website.

However, if you copy a token with elevated permissions and use it outside of FreeFlarum, it will still have elevated permissions. It is recommended that you provide third-party services with normal tokens.

"Remember me"⚓︎

By default, the "Remember me" box is not ticked when logging in to FreeFlarum, and so your access token will expire in 1 hour. This is recommended for one-time third-party services (if they finish the task within 1 hour), so that the token is no longer valid after 1 hour.

If you tick the "Remember me" box, the token is then valid forever (in other words, you won't be logged out unless the access_token cookie is deleted, e. g.: after clearing browsing history).

Creating new access tokens⚓︎

You have 2 options to create access tokens:

  1. Log in through FreeFlarum's website;
  2. Send an API request to https://api.freeflarum.com/authentication.

The first method is ideal if you can't create an API request or you simply aren't a technical type, but need the access token for some third-party service. To do it this way while staying logged in via your main token, open a new private browsing/incognito session or visit FreeFlarum through a different browser/device. Then, log in without ticking the "Remember me" box, and you will have a temporary (1 hour) token, with elevated permissions though. If you don't want elevated permissions, then you will either need to authenticate via api.freeflarum.com or forge an API request.

The second method is ideal for obtaining tokens without elevated permissions, and is described in the API documentation.

Revoking access tokens⚓︎

Again, you have 2 options:

  1. Log in to FreeFlarum.com and revoke it by clicking the trash bin icon on the left of the access token;
  2. Use access token with elevated permissions and send an API request.

Please note that changing your forum admin's password won't revoke existing access tokens (this is due to technical limitations - FreeFlarum's Python backend can't communicate with Flarum's PHP backend easily). If you change your password because of security reasons (e. g.: unauthorized use of your access token or password leak), you will need to revoke all existing access tokens manually (see methods available above).