Prepare an authorization link for one intended social account connection.
Before you start
- Verify production, original organization/user, native accounts:write permission and the intended accessible canonical Socialize workspace. Bind the workspace separately; platform string is not a resource grant.
- Confirm that the human intends to connect the provider and review its consent scopes. Preparing a link is a mutation and does not approve external consent; use the real returned URL only in the intended browser and verify its origin. Keep OAuth state/authorization URLs out of logs and ordinary shared context.
- All examples are synthetic UNRUN with reserved .invalid domains and fictional credentials/state. No authorization state, provider account, token exchange or live credential lookup was created by documenting them. Source association is not serving-artifact or current-provider configuration proof.
Request
POST /api/integrations/{platform}/connect
Action: app_topolo_socialize.integrations.connect.
Behavior and partial effects
Use platform from the published available integration selection. This route searches exact supported ids and refuses unsupported/coming-soon entries; arbitrary nonempty platform passes structural validation but can still return400. The path parameter selects provider. Optional callbackUrl is accepted by the native input schema but this handler never reads it; it does not override provider redirect or post-connection destination.
The handler authenticates, resolves the brand workspace and owning organization, then requests the Nexus-owned provider credential in that scope. Transient dependency unavailable returns503/retryable; genuinely absent configuration returns409/nonretryable. Production TikTok configured for sandbox is not connectable here. Do not infer provider readiness from a catalogue declaration.
A successful start generates a new UUID state, ten-minute expiry and PKCE verifier/challenge. It inserts oauth_states with original user/workspace/platform and settings/integrations return destination. A subsequent SELECT missing the row is only logged, not refused; therefore HTTP200 alone does not prove state was durably retained. CACHE_KV, when present, receives the verifier with600-second TTL; absent KV does not make the route refuse here or establish later callback success.
State insert, optional KV write and final URL construction are sequential, with no encompassing transaction or request idempotency key. Failure or lost reply may leave state/verifier; every repeated start generates a new identity. Do not claim rollback or replay-safe creation. Workspace resolution can also synchronize local mirrors.
Returned payload is exactly authUrl,state,expiresAt. URL uses configured provider authorization endpoint/scopes/redirect or provider defaults; Twitter adds S256 challenge and YouTube requests offline access/consent. The supplied callbackUrl does not determine these settings. No client secret or access token is returned.
This start does not exchange a code, prove human consent, persist a connected social account, publish a post or confirm delivery. Any later callback/exchange must be assessed through its own supported workflow and actual account read-back; do not turn this response into connection success.
Worked examples
Prepare one fictional Twitter authorization
Complete source-derived synthetic UNRUN HTTP200. Assumes clock12:00Z, authorized workspace, configured fictional Nexus credential with public client fixture_public_client, override authorization URL oauth.example.invalid, exact fictional redirect URI shown, scopes[tweet.read], valid packaged English release and a hypothetical64-zero-byte RNG verifier. .invalid endpoints and fake state confer no authority; do not visit them.
{
"platform": "twitter"
}
Illustrative response:
{
"authUrl": "https://oauth.example.invalid/authorize?client_id=fixture_public_client&response_type=code&redirect_uri=https%3A%2F%2Fsocialize-api.example.invalid%2Fapi%2Fintegrations%2Ftwitter%2Fcallback&scope=tweet.read&state=00000000-0000-4000-8000-000000000001&code_challenge=RXJXkcR7MmGMxXuIND4rzuw7CgG4O8l9FEosvBGiDD0&code_challenge_method=S256",
"state": "00000000-0000-4000-8000-000000000001",
"expiresAt": "2026-10-21T12:10:00.000Z"
}
authUrl starts provider authorization only; state is the exact opaque correlation value and expiresAt is ten minutes after assumed creation. No connected-account id, token or successful user consent is returned.
Credential dependency is temporarily unavailable
Complete source-derived synthetic UNRUN HTTP503 under configured source-English copy and transient credential resolution failure. This refusal is not a successful outputSchema witness or proof that credentials are absent.
{
"platform": "twitter"
}
Illustrative response:
{
"error": "integration_dependency_unavailable",
"code": "integration_dependency_unavailable",
"message": "X is temporarily unavailable. This is usually a brief hiccup \u2014 please try again in a moment.",
"status": "unavailable",
"platform": "twitter",
"retryable": true,
"recovery": "Retry the action. If it continues, inspect Auth service-token exchange and Nexus availability using the request ID."
}
Branch on integration_dependency_unavailable, retain request/scope and wait for changed dependency health. Do not mint a replacement key, switch environment or loop new authorization starts.
Verify and recover
Validate the complete success object, verify state matches the state parameter in its actual returned URL and note expiry, original provider and workspace. Treat the URL as correlation-sensitive. Do not rewrite OAuth parameters or construct a callback URL from examples.
The human must complete real provider consent in the intended browser before connection read-back. Afterwards use the published integrations list in the same authorized scope; verify the actual provider/account identity and capabilities. A successful start or a linked local record is not an external posting/delivery health check.
No automatic inverse for state/KV/mirror writes is published. On timeout or error preserve request id, original scope and uncertain partial state; do not blindly repeat, revoke an unrelated connection or guess state cleanup. A distinct authorization start requires a reasoned human-intended new flow after reconciling the original. For transient dependency failure wait for changed health; for misconfiguration refer to the provider configuration owner without exposing credentials.
Changelog
2026-10-21: source-qualified authorization preparation, ignored callbackUrl, state/KV partial outcomes and distinct provider-consent boundary. Synthetic UNRUN examples; no serving, consent, token or delivery certification.