Skip to Main
View .mdAsk ClaudeAsk ChatGPT

OAuth 2.0 (Pro) lets HuxxConnect call APIs that don’t accept a plain key — Google, GitHub, Salesforce, and the like. You authorize once in the browser; after that, HuxxConnect attaches the access token to every request and renews it automatically.

Quick version:

  1. In your OAuth provider’s developer console, create an app and register this redirect URI: https://your-site.example/wp-admin/admin-post.php?action=huxx_connect_oauth_callback
  2. API detail page → set the API’s auth type to OAuth 2.0.
  3. Click a Provider preset tile (Google, GitHub, Salesforce, …) — it fills Authorization URL, Token URL, scopes, and PKCE. Or pick Custom and fill them yourself.
  4. Paste Client ID and Client Secret, adjust Scopes, and save the API.
  5. Click Authorize, approve at the provider, and land back with a Connected badge. Done — refresh is automatic.

Pick a grant type

The Grant Type select supports the two server-side OAuth 2.0 flows:

  • Authorization Code (default) — for APIs that act on behalf of a user account. You’re redirected to the provider to approve access; HuxxConnect exchanges the returned code for an access token and, when the provider issues one, a refresh token.
  • Client Credentials — for server-to-server APIs with no user approval step. HuxxConnect requests a token directly from the Token URL using your client credentials; there’s no redirect and no refresh token (a fresh token is requested when the old one expires).
New to APIs? Read this first

OAuth is the “Sign in with Google” pattern: instead of giving HuxxConnect your password, you approve access once on the provider’s own site, and the provider hands back a temporary pass. Understanding Authentication explains where OAuth fits among the other auth types.

Register the callback URL with your provider

Authorization Code flows need the provider to know where to send you back. HuxxConnect’s callback URL is shown read-only in the Redirect URI field with a copy button; its format is always:

https://your-site.example/wp-admin/admin-post.php?action=huxx_connect_oauth_callback

Add it verbatim as a redirect/callback URI in your OAuth provider’s app settings. Providers reject even small mismatches (http vs https, a trailing slash), so copy it rather than retyping. The callback only works for a logged-in WordPress administrator — it verifies the HuxxConnect capability and a state parameter before accepting anything.

Use a provider preset

Setting the API’s auth type to OAuth 2.0 reveals the Provider section: tiles for Custom plus twelve presets — Google, Facebook, Instagram, Microsoft, GitHub, Salesforce, HubSpot, Shopify, Amazon v3.x (LwA), Slack, LinkedIn, and Dropbox.

Clicking a tile fills the Authorization URL, Token URL, default scopes, grant type, PKCE setting, and token request format for that provider, and shows a one-line hint about where to create your app (e.g. Google: “Create credentials at console.cloud.google.com under APIs & Services > Credentials. Scopes vary by API.”). Two presets need extra attention:

  • Shopify — the preset URLs contain a {shop} placeholder; replace it with your store name.
  • Amazon v3.x (LwA) — a Client Credentials preset that also switches Token Request Format to JSON, which Login with Amazon requires.

For any other provider, choose Custom and paste the Authorization URL and Token URL from its documentation.

Fill in credentials and scopes

  • Client ID / Client Secret — from your provider’s app settings. Both are credentials: the secret is stored through HuxxConnect’s encrypted credential store, never in plain text.
  • Scopes — a tag input; type a scope and press Enter, space, or comma to add it. Most presets seed starter scopes; some (Google, Slack, Dropbox, Amazon) leave the field empty because scopes depend on which API you call. Either way, the scopes must cover every endpoint you plan to call. Leave empty if the provider doesn’t require any.
  • Enable PKCE — Proof Key for Code Exchange, on by default for providers that support it. Recommended whenever your provider supports it; turn it off only if the provider rejects PKCE parameters.
  • Token Request Format — how the token request body is encoded: Form (default) or JSON. Most providers use Form; change it only when the provider’s docs say so.

Save the API before authorizing — the Authorize button stays disabled with a “Save changes before authorizing.” notice while there are unsaved edits.

Authorize and verify

Click Authorize (labeled Request Token for Client Credentials). For Authorization Code you’re sent to the provider’s consent screen; approve, and you return to the API detail page with an “OAuth authorization successful!” toast.

The status area then shows a badge:

Connected    Expires 7/19/2026, 3:42:00 PM
  • Connected — a valid access token is stored.
  • Token Expired — the access token lapsed; the note “Will auto-renew on next API request.” means exactly that, no action needed if a refresh token exists.
  • Not Connected — no tokens stored yet, or they were revoked.

Re-authorize repeats the flow (needed after changing scopes); Revoke deletes the stored tokens.

How tokens are stored and refreshed

Access and refresh tokens are encrypted with your site’s HuxxConnect encryption key and stored per API in the WordPress options table — they never appear in the admin UI. On each request, if the access token is within 30 seconds of expiry, HuxxConnect refreshes it first: Authorization Code APIs use the stored refresh token (kept across renewals even when the provider doesn’t reissue one), and Client Credentials APIs request a new token outright. Only if refresh fails does the request go out without a token — at which point the status badge shows the problem.

If it didn’t work

“OAuth authorization failed: provider denied access” (or an error about the redirect URI). The registered redirect URI doesn’t exactly match the one in the Redirect URI field, or the provider app is missing the required scopes/products. Copy the URI again with the copy button and compare character-for-character in the provider console.

“OAuth authorization failed: session expired. Please try again.” The state parameter that protects the flow timed out between clicking Authorize and returning. Click Authorize again and complete the consent screen without long pauses.

“OAuth authorization failed: token exchange failed.” The provider rejected the code-for-token exchange — almost always a wrong Client Secret, a wrong Token URL, or the wrong Token Request Format. Re-check the secret, then try switching the format if the provider’s docs mention JSON bodies. Debug API Requests shows how to read the underlying request log.