XenForo API Setup & Troubleshooting Guide

XFtoWP offers a simple interface to setup and manage your API connection. To start syncing data to first-time installations and create a secure API user, follow this guide.

Requirements

1. You are running XenForo 2.2+ and WordPress 5.0+
2. Your site has the “Use Full Friendly URLs” option enabled (XenForo Admin > Options > Basic Setup)
   Tip: To bypass this option, add index.php to the end of your Board URL.
3. Neither sites are password-protected with .htpasswd
4. Your XenForo site is not in maintenance mode
5. Confirm your XenForo API is active by testing this URL in your browser:
   https://yourXFinstall.com/api/
   Non-friendly URL: https://yourXFinstall.com/api/index.php
   

Creating a XenForo API User

Go to: XenForo Admin > Options > API Keys > Add API key

For your WordPress website to be able to interact with your forum you must first create an API key, and in most cases, setup an API user. To best do this, you should only grant access and permissions to the features you want.

For example, if you only want to use Thread connect to link forum threads to blog posts, and are not interested in User syncing, you only need to enable API user permissions related to threads.

Additionally, the forum user you set as the API user must also have the permissions to carry out an API action.

To read and create new threads, the API user must also have the same permissions at the forum. The same applies when syncing users, and the API user must have the Administrator privilege to “Manage Users & Moderators”.

Do not show private forums and posts to the API user or it may end up syncing content you don’t wish to show across websites. You should only grant the most bare minimum permissions and access to your API users.

Next, let’s review how to choose the right API Key type for your site:

API Key Types

There are three kinds of API Key Types, as quoted from the XenForo REST API documentation:

• Guest key – this key always accesses the API as a guest user. These requests will always respect the guest permissions. For example, if guests cannot reply to threads, an API request to reply to a thread would generate a no permission error.
• User key – this key always accesses the API as a specified user and always respects that user’s permissions, similar to a guest key.
• Super user key – this key can access the API as any user by passing an additional value into it. Optionally, this key can bypass the requesting user’s permissions, allowing them to take actions or view content they would not normally have access to.

It is recommended you create a User key, but if you require any of the features below you must use a Super User key:

• Send alerts (alert:write)
• Generate auto-login links (auth:login-token)

Supported permissions

The following API permissions are compatible with XFtoWP. It is strongly recommended to only enable the permissions for the features you expect to use. These permissions can be changed later.

• alert:write
• auth
• auth:login_token
• conversation:write
• node:read
• thread:read
• thread:write
• user:delete
• user:read
• user:write

Once you have setup your API key accordingly, save your settings to publish your new XenForo API key!

Making the connection

With your API permissions now setup, go to WP Admin > XenForo > Site Setup and simply enter your Board URL, XenForo API Key, and API Super User ID (if applicable) to the XFtoWP settings page.

Once you have entered the Forum URL & API key click the Save button at the top. The page will reload and you will see the new Refresh forum data button which you can press to officially fetch your first forum data!

If your sync is successful, you will see the name of your forum at the top of the XFtoWP dashboard with a Last sync date, and are ready to use the available options of the plugin.

Having connection issues?

If you are getting an error or your data doesn’t seem correct, go back to the start of this guide and review each setup requirement is met. If your connection issues persist, you can start a thread at the XFtoWP support forums for help.

Other troubleshooting tips:

1. Install the Query Monitor plugin to track any possible errors
2. Data not syncing? In old versions of a popular plugin developer library called Freemius there is a conflict that blocks API calls from being made. Identify if a plugin uses Freemius and disable it to run another test sync.
   References: XFtoWP forums | Google Search
3. There have been reported issues of sites not being able to make API requests when using Ezoic.
   References: XFtoWP forums

Originally published on November 27, 2020 6:21pm