Connecting your Discourse forum

Connecting your forum means pasting one thing from Discourse into your portal, and two things from your portal into Discourse. Then you test the connection, and turn sign-in on when every check passes.

Keep two tabs open: your Discourse admin, and the Discourse tab in your Customer portal. Click Connect your forum to start.

1. Create an API key in Discourse

In Discourse, go to Admin → Advanced → API keys and click New API key.

• Description: anything you'll recognise later, like "Magic Pages".
• User level: All users.
• Scope: Granular, then tick these:
  • users: sync sso, show, suspend, anonymize, delete, log out
  • groups: administer groups
  • global: read

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

[Screenshot: the Discourse API key form with the granular scopes ticked]

2. Fill in the form in your portal

Under Your Discourse forum:

• Forum address: your forum's address, starting with https://, like https://community.example.com. Use the address the forum ends up on, with or without www.
• Admin API key: the key you just copied. We store it encrypted and never show it again.
• When a member is deleted in Ghost: what happens to a deleted member's forum account. Suspend their forum account is the default, and you can undo it. See what each choice does.

3. Paste two settings into Discourse

The Paste these into Discourse card holds two values. In Discourse, go to Admin → Settings → Login and search for "discourse connect".

• discourse connect url: copy it from your portal. It's your site's address followed by /content/files/discourse/sso.
• discourse connect secret: click Copy. We created this secret for your site, so only paste it into Discourse.

4. Change the other settings

Still in Discourse's settings, search for each of these:

• Turn on enable discourse connect. This is the one that sends forum sign-ins to your site, so do it after the two settings above.
• Turn on auth overrides name, so name changes in Ghost reach the forum.
• Turn off email editable, then turn on auth overrides email, so email changes in Ghost reach the forum.
• Set max username length to 30. Discourse counts group names as usernames, and its default of 20 is too short for many tier names. There's more on group names here.

From the moment enable discourse connect is on, the forum's Log in button goes to your site. Members see "Forum sign-in is turned off for this site" until you finish step 6, so do steps 4 to 6 in one go.

If you ever lock yourself out of the forum, open yourforum.com/u/admin-login and Discourse emails you a sign-in link.

5. Test the connection

Back in your portal, click Test connection. It saves the form and checks eight things, in order:

Fix what's listed in Discourse and click Test connection again. If the test says "Your forum is limiting requests", wait the seconds it gives you, then test again.

You can close the form after a failed test and come back to it later. Edit settings opens it again with every field, the forum address included.

[Screenshot: a passed connection test]

6. Turn on forum sign-in

When every check passes, click Turn on forum sign-in. We create a group in Discourse for each paid tier straight away.

Then try it yourself: open your forum in a private window, click Log in, and sign in with a member's email.

What you see afterwards

The Forum sign-in card shows how many members are on the forum, how many tier groups are synced, when the last sync ran, and what happens to deleted members. Edit settings opens the form again, and Open forum takes you to the forum.

Below it, the Tier groups card lists every tier and its forum group. Use the groups to keep categories for paying members.