Connecting your WordPress site allows you to publish content directly from your dashboard. While the setup is usually straightforward, security settings, server configurations, or plugin conflicts can sometimes interfere with the connection. This guide helps you identify and resolve the most common WordPress integration issues.

Setting up Application Passwords

For self-hosted WordPress sites, we use Application Passwords. This is a secure way to allow external applications to interact with your site without sharing your main login password.

How to generate an Application Password:

1. Log into your WordPress Admin dashboard (e.g., yourwebsite.com/wp-admin).

2. Navigate to Users > Profile.

3. Scroll down to the Application Passwords section.

4. In the New Application Password Name field, enter a name like "Outrank Integration".

5. Click Add New Application Password.

6. Copy the generated password immediately. It is a 24-character string (e.g., abcd efgh ijkl mnop qrst uvwx).

[Screenshot Placeholder: WordPress User Profile showing the Application Passwords section with a new password generated]

Troubleshooting Authentication Failures

If you receive an error while trying to connect, it is usually related to credentials or server permissions.

401 Unauthorized Error

This error means the site rejected your credentials. To fix this:

• Check your username: Ensure you are using the exact username (not the email address) associated with the WordPress profile where you generated the password.

• Verify the password: Ensure you copied the entire 24-character Application Password. Do not use your regular WordPress login password.

• Check for spaces: While WordPress displays the password with spaces for readability, you should copy it exactly as shown.

403 Forbidden Error

A 403 error means your server or a security plugin is blocking the connection request. This is common if you use services like Cloudflare or security plugins like Wordfence.

Resolving REST API Issues

Our integration relies on the WordPress REST API. If the API is disabled or misconfigured, the connection will fail.

Check your Permalinks

The REST API requires "Pretty Permalinks" to function correctly. If your site uses "Plain" permalinks, the API endpoints may return a 404 error.

1. Go to Settings > Permalinks.

2. Ensure Post name (or any option other than "Plain") is selected.

3. Click Save Changes to refresh your site's rewrite rules.

Security Plugin Conflicts

Some security plugins disable the REST API by default. Check the settings of the following plugins if you have them installed:

• Wordfence: Ensure "Disable WordPress Application Passwords" is not checked.

• NinjaFirewall: Check for rules blocking wp-json requests.

• Disable REST API: If you have this specific plugin, you must whitelist our service or deactivate the plugin.

Fixing Publishing and Image Errors

Sometimes the connection is successful, but you encounter errors when trying to publish an article.

Image Upload Failures

If your article publishes but images are missing, it is usually due to:

• File Size Limits: Your WordPress site or hosting provider may have a low upload_max_filesize limit.

• Folder Permissions: Ensure your wp-content/uploads folder is writable (usually permission level 755).

502 Bad Gateway or Timeouts

If you see a 502 error during publishing, it often means your server timed out while processing the request. This can happen with very long articles or slow hosting environments. Try publishing the article again; often, a second attempt succeeds once the server resources are ready.

Cloudflare and Firewall Configuration

If your site is behind a firewall, you may need to whitelist our service to allow the integration to communicate with your site.

• WAF Rules: Create a rule in Cloudflare to allow traffic to the /wp-json/ path.

• IP Whitelisting: If your host requires specific IP addresses to be whitelisted, please contact our support team for the current list of integration server IPs.

Still having trouble?

If you have followed these steps and still cannot connect, please contact our support team with the specific error code you are seeing. Including a screenshot of your Settings > Permalinks page and your Users > Profile page can help us diagnose the issue faster.