If your website has memberships, programs, or products, you can decide which forum user groups each member belongs to. Your website sets the rules and passes the group IDs to the forum, so a member's forum access always matches their membership on your website.
How It Works
- Which groups to assign. Your website works out the right groups for each member and passes them to the forum.
- Whether to start single sign on. If the member's products or programs have expired, your website simply does not log them into the forum.
The forum never reads your membership records itself. Everything is driven by your website.
Before You Start
- Get your API Key. You need it for every request in this article.
- Get the ID of each user group you want to assign, such as one group per program.
Assign Groups When an Account Is Created
Include the userGroups parameter in your single sign on log in request. If the account does not exist yet, it is created with those groups.
Separate multiple IDs with commas. These groups apply when the account is first created. To change groups later, use the API requests in the next section.
Update Groups When Membership Changes
When a member buys, upgrades, or loses a program on your website, update their forum groups with the Website Toolbox API. These requests run from your server, so you can make them the moment the change happens. The member does not need to be logged in.
Update all of a member's groups in one request
To make several changes at once, such as adding a member to two groups and removing them from one, send one request to the member's endpoint with every group they should belong to. The groups you send replace the member's current groups, so include any groups you want them to keep.
To see the member's current groups before you replace them, send a GET request to the same address.
The response includes the member's current userGroups.
Add or remove one group
When you only need to grant or revoke a single group, use the group's endpoint instead so you do not have to send the full list.
USER_ID is the member's forum user ID, which the log in request returns when the account is created. You can pass usernames or email addresses instead of user IDs. An email address for someone who does not have a forum account yet sends them an invitation to the group instead.
Deciding Who Gets Access
Your website checks the member's membership before starting single sign on. If they still have access, log them in with the token as described in Single Sign On - Token Based Authentication. If their products have expired, do not start single sign on and they will not be logged into the forum.
Frequently Asked Questions
Should I update the member's groups or use the group's endpoint?
Send the full list of groups to the member's endpoint when you are changing several groups at once. Use the group's endpoint when you are only adding or removing one group.
When should I update a member's user groups?
Update the groups whenever the member's membership changes on your website, such as a purchase, an upgrade, or an expiration. There is no need to wait for the member's next log in.
Does the member need to be logged in for the groups to update?
No. The update is an API request from your server, so it works whether or not the member is logged in or visiting the forum.
What is curl?
Curl is a command line tool for sending HTTP requests that is included with macOS, Linux, and recent versions of Windows, which is why the examples in this article are written as curl commands. You can send exactly the same requests from any programming language using its standard HTTP tools, with the same parameters in every language. See Sample code for making an HTTP request for examples in several languages.
Why does an API request fail?
Check that the API key matches your forum's API key, that the group ID and user ID are correct, and that the member already has a forum account.