Skip to main content
Back to API docs

Headless connect API

Headless Connect API for End-User Account Linking

Headless Connect links end-user social accounts from your own website without sending them through the Wahdx dashboard. Your backend starts a connect session with the X-API-Key header, sends the end-user browser to the provider authorization URL, and receives the browser back at the redirect URL configured for the workspace, with a one-time code. Your backend then exchanges that code for the linked account. Access tokens stay on Wahdx servers, and your workspace receives only the account id and non-sensitive profile fields. Headless Connect requires the Maximum plan and works with TikTok, Instagram, Threads, Facebook, YouTube, and Pinterest.

How the flow works

Four steps run end to end. Your backend is the only party that holds the API key and exchanges the one-time code.

  • Configure the https redirect URL for the workspace in the dashboard profile page, under Headless Connect.
  • Start a session with POST /api/connect/sessions. The response returns connectId, authorizationUrl, and expiresIn in seconds.
  • Send the end-user browser to authorizationUrl. The provider redirects back to Wahdx, then Wahdx sends the browser to the configured redirect URL.
  • Exchange the code from that redirect with POST /api/connect/sessions/:connectId/complete to read the linked accounts.

Configure the redirect URL

The redirect URL is set per workspace in the dashboard profile page, not through the API. A session starts only when its redirectUrl matches a configured URL exactly. URLs must be https, absolute, without credentials or a fragment, and each workspace can store up to 10. Trailing slashes are normalized and query strings are preserved. Sign in to the dashboard, open the profile page, and add the URL under Headless Connect.

Start a connect session

Send the platform, the allowlisted redirectUrl, and an optional connectionId to track the flow in your own system. The response returns connectId, the provider authorizationUrl, and expiresIn (600 seconds). Redirect the end-user browser to authorizationUrl as a top-level navigation. The authorizationUrl below is truncated; at runtime it contains the full provider URL with a bound state value.

const API_BASE_URL = 'https://api.wahdx.com';
const API_KEY = process.env.WAHDX_API_KEY;

const response = await fetch(API_BASE_URL + '/api/connect/sessions', {
  method: 'POST',
  headers: {
    'X-API-Key': API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    platform: 'instagram',
    redirectUrl: 'https://your-site.example/oauth/callback',
    connectionId: 'order-42'
  })
});

const { data } = await response.json();
// Send the end-user browser to data.authorizationUrl
console.log(data.connectId, data.authorizationUrl, data.expiresIn);
Example response · 201
{
  "success": true,
  "data": {
    "connectId": "7f9c2a10-1b2c-4d3e-8f90-abcdef123456",
    "authorizationUrl": "https://www.instagram.com/oauth/authorize?client_id=...&state=...",
    "expiresIn": 600
  }
}

Complete the handoff

After the end-user authorizes, the provider returns the browser to your redirectUrl with connectId, code, and status query parameters. Send connectId and code to the complete endpoint from your backend. The code is valid for 120 seconds and can be redeemed once; a second attempt with the same code fails. Every platform returns an accounts array, including platforms that link a single account.

const API_BASE_URL = 'https://api.wahdx.com';
const API_KEY = process.env.WAHDX_API_KEY;

const connectId = 'CONNECT_ID_FROM_REDIRECT';
const code = 'CODE_FROM_REDIRECT_QUERY';

const response = await fetch(
  API_BASE_URL + '/api/connect/sessions/' + encodeURIComponent(connectId) + '/complete',
  {
    method: 'POST',
    headers: {
      'X-API-Key': API_KEY,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({ code })
  }
);

const { data } = await response.json();
console.log(data.status, data.accounts);
Example response · 200
{
  "success": true,
  "data": {
    "status": "success",
    "platform": "instagram",
    "connectionId": "order-42",
    "accounts": [
      {
        "accountId": "acc_instagram_internal_uuid",
        "platform": "instagram",
        "username": "wahdx.studio",
        "displayName": "Wahdx Studio"
      }
    ]
  }
}

Redirect parameters

Wahdx appends these query parameters to your allowlisted redirectUrl. On success the browser receives connectId, code, and status=success. When the flow fails, it receives connectId, status=error, and error.

Query parameters sent to the tenant redirect URL
ParameterMeaning
connectIdIdentifies the session you created. Send it in the complete request.
codeOne-time handoff code, present only when status is success.
statussuccess when an account was linked, error otherwise.
errorError value, present only when status is error.

Complete response fields

The complete endpoint returns status, platform, your connectionId, and an accounts array. Every platform returns an array, including platforms that link a single account. Facebook can return one entry per managed Page.

Account fields in the complete response
FieldMeaning
accountIdInternal account id used in later publish and status calls.
platformThe connected platform.
usernameAccount handle when the platform exposes one.
displayNameAccount or Page display name.

Unlink a connected account

DELETE /api/connect/accounts/:platform/:accountId removes an account from the workspace from your backend. The platform is one of tiktok, instagram, threads, facebook, youtube, or pinterest, and accountId is the internal id from the complete response or GET /api/content/accounts. The unlink is permanent: Wahdx deletes the stored credentials and frees the account identity so the same account can be linked again later. The account is also removed from every pending scheduled post: a post is cancelled only when this account was its only target, and otherwise it stays scheduled for the remaining accounts. If a post for this account is currently processing, the unlink is rejected with 409 ACCOUNT_BUSY. The response reports action (deleted) and a best-effort revoke result for the provider token.

const API_BASE_URL = 'https://api.wahdx.com';
const API_KEY = process.env.WAHDX_API_KEY;

const platform = 'tiktok';
const accountId = 'ACCOUNT_ID_FROM_CONNECT';

const response = await fetch(
  API_BASE_URL + '/api/connect/accounts/' + encodeURIComponent(platform) + '/' + encodeURIComponent(accountId),
  {
    method: 'DELETE',
    headers: { 'X-API-Key': API_KEY }
  }
);

const { data } = await response.json();
console.log(data.action, data.revoke);
Example response · 200
{
  "success": true,
  "data": {
    "platform": "tiktok",
    "accountId": "acc_tiktok_internal_uuid",
    "action": "deleted",
    "revoke": "revoked"
  }
}

Unlink response fields

The endpoint returns the platform and accountId you sent, plus the action taken and the provider token revoke result.

Fields in the unlink response
FieldMeaning
platformThe platform you unlinked from.
accountIdThe internal account id that was removed.
actiondeleted when the account was removed.
revokerevoked when the provider token was revoked, unsupported when the platform has no revoke API, or failed when revoke was attempted and did not succeed.

Unlink error codes

The unlink endpoint uses the same envelope as the rest of Headless Connect, so your backend can react without guessing.

  • 400 INVALID_ACCOUNT_IDENTITY: the platform is not one of the six supported values.
  • 400 Invalid accountId: accountId is not a valid account id.
  • 403 HEADLESS_CONNECT_PLAN_REQUIRED: the workspace is not on the Maximum plan, so the account is left untouched.
  • 404 ACCOUNT_NOT_FOUND: the account does not exist in this workspace.
  • 409 ACCOUNT_BUSY: a scheduled post for the account is processing, or another operation still holds it. Retry after it finishes.
  • 500 ACCOUNT_UNLINK_FAILED: an unexpected failure occurred. Retry, or contact support if it repeats.
  • 503 SUBSCRIPTION_LOOKUP_FAILED: the plan could not be resolved, so retry later.

Error codes

API responses carry a code so your backend can react without guessing.

  • 403 HEADLESS_CONNECT_PLAN_REQUIRED: the workspace is not on the Maximum plan.
  • 400 INVALID_REDIRECT_URL or REDIRECT_URL_NOT_ALLOWED: the redirect URL is invalid or not configured for the workspace in the dashboard.
  • 400 UNSUPPORTED_PLATFORM or INVALID_CONNECTION_ID: the platform is not supported, or connectionId is not a valid string.
  • 400 CONNECT_CODE_INVALID: the handoff code is missing, expired, or already used.
  • 403 CONNECT_SESSION_MISMATCH: the session does not belong to the authenticated workspace.
  • 503 CONNECT_UNAVAILABLE, PROVIDER_CONFIGURATION_MISSING, or SUBSCRIPTION_LOOKUP_FAILED: a dependency is unavailable, so retry later.

Redirect error values

When the flow fails, the redirect carries status=error and one of these error values.

  • no_pages_found: the Facebook user manages no Pages, so nothing can be linked.
  • connected_account_limit_reached: the workspace reached its linked-account limit.
  • account_already_linked: every attempted account was already connected.
  • token_exchange_failed or callback_failed: the provider handoff did not complete.
  • reauth_required: YouTube needs a full reconsent to link this channel.
  • plan_upgrade_required: the workspace dropped below Maximum before the flow finished.
  • handoff_unavailable: the one-time code could not be issued, so start a new session.

FAQ

Common questions about this API topic.

Which plans can use Headless Connect?

Headless Connect requires the Maximum plan. Session requests are rejected with 403 HEADLESS_CONNECT_PLAN_REQUIRED on any other plan.

Do end-users ever see the Wahdx dashboard?

No. The end-user browser goes to the provider and returns to the redirect URL configured in the dashboard. Account details and tokens are never shown to the end-user.

Where do access tokens live?

Access tokens stay on Wahdx servers. The complete response returns only an accountId and non-sensitive profile fields.

How often can a connect code be used?

A handoff code is valid for 120 seconds and can be redeemed once. A second attempt with the same code fails with 400 CONNECT_CODE_INVALID.

Can I use Headless Connect from the browser?

No. Keep the X-API-Key server-side. Start sessions and exchange codes from your backend, and send the end-user browser only to the authorizationUrl and your own redirect URL.

How do I configure the redirect URL, and what formats are allowed?

Add it in the dashboard profile page under Headless Connect; the redirect URL is not managed through the API. Up to 10 https URLs per workspace, matched exactly. URLs must be absolute, without credentials or a fragment. Trailing slashes are normalized and query strings are preserved.

What happens if the workspace has no configured redirect URL?

POST /api/connect/sessions is rejected with 400 REDIRECT_URL_NOT_ALLOWED. Add the URL in the dashboard profile page first.

Does removing a redirect URL in the dashboard affect a running flow?

No. The URL is bound into the session when you create it, so a running flow keeps using the URL it started with. Start a new session to use a different URL.

Which plans can unlink an account through the API?

The unlink endpoint is part of Headless Connect, so it requires the Maximum plan. Any other plan is rejected with 403 HEADLESS_CONNECT_PLAN_REQUIRED and the account is left untouched.

Can an unlink be undone?

No. Unlinking is permanent: the stored credentials are deleted and the account identity is freed. The account is removed from pending scheduled posts, and a post is cancelled only when this account was its only target; a post that is currently processing blocks the unlink with 409 ACCOUNT_BUSY. To use the account again, run a new connect session.