OAuth2 Authentication

OAuth2 is the recommended authentication method for production stores. Instead of entering your Mautic login credentials, you create a dedicated set of API credentials in Mautic and authorize the plugin through a secure redirect flow. The plugin then uses short-lived access tokens that are refreshed automatically.

Step 1: Enable the API in Mautic

Log in to your Mautic instance as an administrator.
Go to Settings (gear icon) > Configuration.
Click the API Settings tab.
Set API enabled? to Yes.
Click Save & Close.

Note: You do not need to enable HTTP Basic Auth when using OAuth2.

Step 2: Create API Credentials in Mautic

In Mautic, go to Settings (gear icon) > API Credentials.
Click New.
Select OAuth 2 as the authorization protocol.
Enter a name for the credentials (for example, “WooCommerce Integration”).
In the Redirect URI field, paste the redirect URI shown in the plugin settings (see below for the format).
Click Save & Close.
After saving, Mautic will display a Client ID (also called Public Key) and a Client Secret (also called Secret Key). Copy both values.

Finding Your Redirect URI

The redirect URI is displayed in the plugin settings under the OAuth2 section. It follows this format:

https://yoursite.com/wp-admin/admin.php?page=mautic-integration-woocommerce&mautic_woo_oauth_callback=1

You must copy this URI exactly as shown and paste it into Mautic. If the URI does not match, the authorization flow will fail.

Step 3: Enter Credentials in the Plugin

In WordPress, go to WooCommerce > Mautic Integration.
On the Connection tab, enter your Mautic URL (for example, https://your-mautic.com).
Under Authentication Method, select OAuth2.
Enter the Client ID you copied from Mautic.
Enter the Client Secret you copied from Mautic.
Click Save Changes.

You must save your settings before proceeding to the authorization step. The plugin needs the saved credentials to build the authorization URL.

Step 4: Authorize the Connection

After saving, click the Authorize with Mautic button.
You will be redirected to your Mautic instance.
If you are not already logged in to Mautic, log in when prompted.
Mautic will ask you to authorize the application. Click Authorize.
You will be redirected back to your WordPress admin with a success message.

If the authorization succeeds, you will see a green “Authorized” label next to the Authorize button. If it fails, you will see an error message. Double-check your credentials and redirect URI, then try again.

Security Details

CSRF Protection

The plugin includes a state parameter in the authorization request. This is a WordPress nonce that is verified when Mautic redirects back to your site. It prevents cross-site request forgery attacks by ensuring that the callback originated from a legitimate authorization request initiated by your site.

Encrypted Storage

The Client Secret, access token, and refresh token are all encrypted at rest using AES-256-CBC encryption. Even if your database is compromised, these values cannot be read without your WordPress secret keys.

Automatic Token Refresh

OAuth2 access tokens expire after a set period (typically one hour). The plugin automatically refreshes the access token using the refresh token before it expires. You do not need to re-authorize unless your Mautic API credentials are revoked or your refresh token becomes invalid.

If a request fails with a 401 (Unauthorized) error, the plugin will attempt to refresh the token and retry the request once before reporting a failure.

Troubleshooting

“Invalid OAuth state” – The CSRF verification failed. This can happen if you waited too long before authorizing. Try clicking the Authorize button again.
“OAuth2 authorization failed” – Check that your Client ID, Client Secret, and Redirect URI are all correct. Also verify that the API is enabled in Mautic.
Redirect URI mismatch – The redirect URI in your Mautic API credentials must exactly match the one shown in the plugin settings. Make sure there are no extra spaces or characters.