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);
import os
import requests
API_BASE_URL = 'https://api.wahdx.com'
API_KEY = os.environ['WAHDX_API_KEY']
response = requests.post(
API_BASE_URL + '/api/connect/sessions',
headers={
'X-API-Key': API_KEY,
'Content-Type': 'application/json',
},
json={
'platform': 'instagram',
'redirectUrl': 'https://your-site.example/oauth/callback',
'connectionId': 'order-42',
},
timeout=30,
)
data = response.json()['data']
# Send the end-user browser to data['authorizationUrl']
print(data['connectId'], data['authorizationUrl'], data['expiresIn'])
curl -X POST "https://api.wahdx.com/api/connect/sessions" \
-H "X-API-Key: $WAHDX_API_KEY" \
-H "Content-Type: application/json" \
--data-raw '{
"platform": "instagram",
"redirectUrl": "https://your-site.example/oauth/callback",
"connectionId": "order-42"
}'
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);
import os
import requests
API_BASE_URL = 'https://api.wahdx.com'
API_KEY = os.environ['WAHDX_API_KEY']
connect_id = 'CONNECT_ID_FROM_REDIRECT'
code = 'CODE_FROM_REDIRECT_QUERY'
response = requests.post(
f'{API_BASE_URL}/api/connect/sessions/{connect_id}/complete',
headers={
'X-API-Key': API_KEY,
'Content-Type': 'application/json',
},
json={'code': code},
timeout=30,
)
data = response.json()['data']
print(data['status'], data['accounts'])
curl -X POST "https://api.wahdx.com/api/connect/sessions/CONNECT_ID_FROM_REDIRECT/complete" \
-H "X-API-Key: $WAHDX_API_KEY" \
-H "Content-Type: application/json" \
--data-raw '{
"code": "CODE_FROM_REDIRECT_QUERY"
}'
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| Parameter | Meaning |
|---|
| connectId | Identifies the session you created. Send it in the complete request. |
| code | One-time handoff code, present only when status is success. |
| status | success when an account was linked, error otherwise. |
| error | Error 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| Field | Meaning |
|---|
| accountId | Internal account id used in later publish and status calls. |
| platform | The connected platform. |
| username | Account handle when the platform exposes one. |
| displayName | Account 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);
import os
import requests
API_BASE_URL = 'https://api.wahdx.com'
API_KEY = os.environ['WAHDX_API_KEY']
platform = 'tiktok'
account_id = 'ACCOUNT_ID_FROM_CONNECT'
response = requests.delete(
f'{API_BASE_URL}/api/connect/accounts/{platform}/{account_id}',
headers={'X-API-Key': API_KEY},
timeout=30,
)
data = response.json()['data']
print(data['action'], data['revoke'])
curl -X DELETE "https://api.wahdx.com/api/connect/accounts/tiktok/ACCOUNT_ID_FROM_CONNECT" \
-H "X-API-Key: $WAHDX_API_KEY"
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| Field | Meaning |
|---|
| platform | The platform you unlinked from. |
| accountId | The internal account id that was removed. |
| action | deleted when the account was removed. |
| revoke | revoked 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.