> ## Documentation Index
> Fetch the complete documentation index at: https://docs.oleria.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Discourse

> Connect Discourse to Oleria to bring community members, administrators and moderators, trust levels, groups, category access, API keys, and the staff action log into your identity and access graph.

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](#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](/integrations/overview#sync-model).

<Note>
  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.
</Note>

## 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

<Steps>
  <Step title="Open the API keys page">
    In Discourse, go to **Admin** -> **Advanced** -> **API keys** and select **New API key**.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Copy the key">
    Select **Save** and copy the key. Discourse shows it only once.
  </Step>
</Steps>

### Prepare for User API key authorization

<Steps>
  <Step title="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*`.
  </Step>

  <Step title="Sign in as an administrator">
    In the same browser, sign in to Discourse with the administrator account Oleria should act as.
  </Step>
</Steps>

## Connect Discourse to Oleria

<Steps>
  <Step title="Open the integration">
    Go to your Oleria workspace, select **Integrations** -> select **Discourse**.
  </Step>

  <Step title="Complete the connection form">
    Select **Continue** and provide the following:

    | Field | Notes |
    | :- | :- |
    | Authentication method | **Admin API key (recommended)** or **Authorize via Discourse (User API key)**. |
    | Discourse site URL | Required. Your site's address, for example `https://<name>.discourse.group`. It must use `https`. |
    | API key | Admin API key only. The key you created. |
    | API username (optional) | Admin API key only. The user an **All users** key acts as. The form prefills `system`; replace it with your dedicated administrator's username. For a **Single user** key, clear the field. |
  </Step>

  <Step title="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.
  </Step>
</Steps>

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`.

<Note>
  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.
</Note>

## 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](mailto:support@oleria.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.