Skip to main content
Connect Discourse to Oleria to see who can administer and moderate your community, which groups can read and post in each category, and which API keys and webhooks can reach your site. Oleria reads this data from the Discourse API with an administrator’s credential, so you can review privileged and non-human access and take action directly from Oleria. This integration works with Discourse sites hosted by Discourse (*.discourse.group), and with sites on your own domain or self-hosted once Oleria support allows that domain (see Known limitations).

​
What Oleria discovers

Once connected, Oleria continuously discovers and maps the following from your Discourse site:
  • Accounts - every member, with their username, name, email address, status (active, suspended, deactivated, or staged), trust level, when they were created, when they were last seen, and when they last changed their password. Administrators are marked as administrators. Oleria shows whether each member has two-factor authentication enabled and whether your site requires it.
  • Non-human identities - Discourse’s own system and AI bot users, every admin API key (with the user it acts as, its scope, who created it, and when it was last used), every webhook that has a signing secret, and the User API keys that administrators and moderators have issued to apps (with the app, scopes, and when each was last used). API keys and webhook secrets appear as credentials. Oleria never reads or stores the key or secret values.
  • Roles - Administrator, Moderator, and Trust Level 0 to 4, and which members hold each one.
  • Groups - automatic groups (such as staff and trust_level_1) and custom groups, with their members and owners, and the trust level a group grants its members. Access granted to Discourse’s everyone group appears on the trust_level_0 group, which contains every signed-in member.
  • Resources - categories and sub-categories, with a link to each one.
  • Access - which groups can see, reply to, or create topics in each category, according to its security settings. Administrators can see every category. If your site doesn’t require login, Oleria also shows which categories anonymous visitors can read. API keys whose scopes are restricted to specific categories are linked to those categories.
  • AI agents - if your site runs Discourse AI and agent discovery is enabled for your Oleria workspace, Oleria discovers each AI agent with its bot user, the groups allowed to use it, its sub-agents, and the tools, language model, and MCP servers it’s configured with.
  • Risks - administrators and moderators without two-factor authentication, administrators not seen in six months, two-factor authentication not required for staff, and admin API keys with All users and Global scope, other than the key Oleria connects with.
  • Activity - the staff action log, including suspensions, role and trust-level changes, impersonation, password changes, API key and webhook changes, site setting changes, and category security changes, and each custom group’s history: members added or removed, owners added or removed, and group setting changes.
Oleria refreshes this data on its regular sync schedule.
Oleria doesn’t import topics, posts, or private messages. Each sync lists members with their email addresses, which Discourse records as a check_email entry in your staff action log.

​
Prerequisites

  • A Discourse administrator account. We recommend a dedicated administrator account for Oleria, so remediation actions and the staff action log clearly show Oleria’s changes.
  • Your site’s address, for example https://<name>.discourse.group.
  • Admin access to the Oleria workspace.

​
Choose how Oleria authenticates

Oleria supports two ways to connect:
  • Admin API key (recommended) - an API key you create in Discourse. A key with Global scope lets Oleria sync and take remediation actions. A key with Read-only scope syncs everything, but remediation actions are disabled.
  • Authorize via Discourse (User API key) - you approve Oleria in Discourse, and Discourse issues a User API key for your administrator account. Discourse limits each User API key to 50 requests a minute and 4,000 a day by default, so syncs of large sites are slower and can reach the daily limit. Use an admin API key for large sites.

​
Create an admin API key

1

Open the API keys page

In Discourse, go to Admin -> Advanced -> API keys and select New API key.
2

Configure the key

Enter a description such as Oleria. For User level, select All users. For Scope, select Global (or Read-only for sync without remediation actions). In Oleria, you’ll enter the dedicated administrator’s username as the API username, so the staff action log shows Oleria’s changes under that account.
3

Copy the key

Select Save and copy the key. Discourse shows it only once.

​
Prepare for User API key authorization

1

Allow Oleria's redirect address

In Discourse, go to Admin -> Settings, search for allowed user api auth redirects, and add https://<your Oleria workspace>/workspace/integrations/discourse/connect*.
2

Sign in as an administrator

In the same browser, sign in to Discourse with the administrator account Oleria should act as.

​
Connect Discourse to Oleria

1

Open the integration

Go to your Oleria workspace, select Integrations -> select Discourse.
2

Complete the connection form

Select Continue and provide the following:
3

Confirm the connection

For an admin API key, select Authenticate. For a User API key, select Authenticate, approve Oleria on the Discourse page that opens, and you’re returned to Oleria. Oleria checks that the credential acts as an administrator who can see members’ email addresses, and that it can read API keys and the staff action log. Find the newly connected site on the Connected tab of your Oleria Integrations page.
If Authenticate fails, Oleria shows the reason. Check that the key hasn’t been revoked, that the API username is an administrator, and that the site URL is correct. For a User API key, check that the redirect address is listed in allowed user api auth redirects.
You can connect each Discourse site to Oleria once. To keep the stored API key when you edit only other fields, leave the API key field empty.

​
Verify the integration

Confirm the Discourse site appears on the Connected tab of your Oleria Integrations page with a status of Healthy. After the first sync completes, you can review the discovered accounts, groups, categories, and API keys in your Oleria workspace.

​
Remediation actions

These actions need an admin API key with Global scope, or a User API key.
  • Disable account - suspends the member, which blocks sign-in and signs them out. Reverting the action lifts the suspension, or, if the member was already suspended until a date, puts that suspension back.
  • Enable account - lifts a suspension. Reverting the action suspends the member again.
  • Add to role - makes the member a moderator, or sets their trust level (Discourse then keeps that level fixed). Reverting the action restores the previous role or trust level. A restored trust level stays fixed; unlock it in Discourse if the member should move between levels automatically again.
  • Remove from role - removes administrator or moderator. Reverting the action makes the member a moderator again. An administrator removal can’t be reverted from Oleria. Trust levels can’t be removed; set a different trust level with Add to role.
  • Add to group and Remove from group - custom groups only. Reverting the action undoes the change.
  • Revoke sessions - signs the member out of every session. This can’t be reverted.
  • Disable non-human identity - revokes an admin API key or a member’s User API key, or deactivates a webhook. Reverting the action restores the key or reactivates the webhook.
  • Create user - creates a member with the name, username, and email address you provide, and optionally adds them to custom groups. The member is inactive unless you choose to activate them, and a generated password is never shown, so they set their own with Forgot password. Reverting the action deletes the member it created.
  • Delete user - permanently deletes a member who has no posts. Oleria won’t delete its own account, Discourse’s system users, administrators, or moderators. Discourse refuses to delete members with posts. This can’t be reverted.
  • Create group - creates a custom group. Reverting the action deletes the group, as long as it still has no members.
  • Revoke access to a category - removes the member from the custom groups that give them access to the category. Oleria won’t do this when the access also comes from everyone, a trust-level or staff group, or the Administrator role, and tells you what to change instead. Reverting the action adds the member back to those groups.
  • Remove external user access - the same as Revoke access to a category, for staged (external) users only.
  • Revoke anonymous access - on a category that everyone can access, grants the same access to trust_level_0 instead, so signed-in members keep their access and anonymous visitors lose it. Reverting the action gives everyone its access back and undoes the trust_level_0 change, keeping any other security changes made since.
Oleria confirms every change by reading it back from Discourse, and keeps these limits:
  • Oleria won’t change, suspend, or sign out the account it connects as, and won’t revoke the API key it uses or any User API key of the member it acts as.
  • Oleria won’t act on Discourse’s system and AI bot users.
  • Granting administrator isn’t offered, because Discourse requires an emailed confirmation for it.
  • Automatic groups and trust-level groups are managed by Discourse. Change a member’s trust level instead of their group.
  • A revert is refused if someone changed the member, key, or webhook in Discourse after the action.

​
Known limitations

  • Oleria shows whether two-factor authentication is enabled, but not which method a member uses.
  • Discourse lists User API keys one member at a time, so Oleria imports the User API keys of administrators and moderators only.
  • Discourse applies one admin API rate limit (60 requests a minute by default) to every admin API key on your site. While Oleria syncs, other integrations that use admin API keys may be rate limited.
  • Sign-in history isn’t available through the Discourse API. Oleria uses each member’s last-seen time instead.
  • Oleria reaches *.discourse.group and *.discourse.org sites. To connect a site on your own domain, first contact Oleria support to allowlist that domain.
  • Re-authorizing a User API key connection, or switching it to an admin API key, doesn’t revoke the previous User API key. It still appears as a non-human identity; revoke it in Discourse under the administrator’s Preferences > Apps.
  • Oleria doesn’t delete members who have posts, and doesn’t anonymize members.
  • Discourse grants category access to groups, not to individual members, so revoking a member’s access to a category removes them from the groups that grant it.
  • Discourse AI agents have no version history or owner in the Discourse API, so Oleria shows each agent’s current configuration only.

​
Contact us

For questions about this integration, contact us at support@oleria.com.