Get OAuth URL API
The Get OAuth URL API starts an OAuth connection flow for a chosen social platform. You call GET /v1/connect/{platform} with an access key, receive a URL in the response, and send the user to that URL to authorize the connection. This page explains the exact request contract, every path and query parameter, the hosted and headless account-selection flows, and how to handle redirects, cancellation, and errors.
Get OAuth URL API — endpoint summary and when to use it
Use this endpoint when a user needs to connect a social account before you can post, schedule, analyze, message, or manage comments for that account. The operation is named Get OAuth URL for a platform: you supply the platform in the path, the endpoint returns a URL, and the user completes authorization at that URL. In the standard flow, any account-choice step is presented in the hosted interface, after which the user is sent onward to redirectUri. For LinkedIn, Facebook, or Google Business, you can instead pass headless=true to build your own account-choice interface, as described in the headless section below. Send the request with the x-access-key header set to your token. The header name is accessKey in the source contract and the wire header is x-access-key, with the token as its value. If the request succeeds, the response body contains a required url string. Send the user to that URL to continue. If the request fails with a 500 response, the body contains a required error string; surface that error to the user or log it and do not redirect to an empty or guessed URL. Check the failure matrix below before shipping redirect handling, because cancellation, denial, and headless selection all return the user through redirectUri or cancelRedirectUri rather than through the JSON response.
Request contract: {{API_BASE_URL}}/v1/connect/{platform}, authorization header, and field map
The request line is GET {{API_BASE_URL}}/v1/connect/{platform}. The origin is modular: replace {{API_BASE_URL}} with the configured base URL and keep the path /v1/connect/{platform} unchanged, including the platform placeholder. The platform path parameter is required, is a string, and must be one of twitter, instagram, youtube, tiktok, pinterest, linkedin, bluesky, facebook, threads, or googlebusiness. Choose the value that matches the account the user is connecting; do not pass display names, uppercase variants, or unsupported platform names. All other parameters are optional query parameters. Omit a parameter entirely when it does not apply rather than sending an empty value, and validate URI-format parameters before sending them so the redirect targets are well-formed. The field map table below separates the header, path, query, and response fields so you can wire validation and logging to the correct location for each value.
Path and query parameters: platform, loginMethod, reconnectAccountId, redirectUri, cancelRedirectUri, headless, profileId, appId
The loginMethod query parameter is Instagram only and accepts instagram_login or facebook_login. When you use facebook_login, Facebook Login requires a linked Page, and a bring-your-own-keys appId must reference a Facebook app. The reconnectAccountId query parameter identifies an Instagram integration to reconnect; account identity must match and existing posts are retained. Its value must match the pattern ^[a-fA-F0-9]{24}$, so validate the 24-character hexadecimal format on your side before calling the endpoint and treat a mismatch as a client-side failure rather than sending the request. The redirectUri query parameter is the final URL to redirect to after the connection completes, in URI format. When headless mode is active, that same destination can also carry status information about selection when you are handling account choice yourself. The cancelRedirectUri query parameter is the URL to redirect to when the user cancels or denies the OAuth prompt, also in URI format; when omitted, it falls back to redirectUri. The headless query parameter is a boolean that defaults to false. Setting it to true hands account choice to your own interface via a short-lived selectionToken delivered back to redirectUri; leaving it false keeps the hosted interface. The profileId query parameter associates the resulting integration with a profile that must belong to the same project; omit it to connect without a profile. The appId query parameter connects under your own OAuth app through bring your own keys: provide the identifier of an OAuth app created via /v1/apps for the same platform, or omit it to use the system app. The input contract table below lists each parameter with its type, requiredness, enum, pattern, format, and default so you can implement validation without guessing.
Headless account-selection flow and selectionToken callback
In the default hosted flow, the user completes any required account choice in the hosted UI and is then returned to redirectUri. In the headless flow, set headless=true for LinkedIn, Facebook, or Google Business when you want to own the selection experience. When a choice is needed, the callback sends the user to redirectUri carrying status=selection_required together with platform and selectionToken. Read those three values from the callback query string, render your own account-choice UI using the platform and selectionToken, and treat selectionToken as short-lived: do not store it as a long-term credential, do not reuse it after it expires, and do not log it in plain text. If no choice is needed, the flow returns to redirectUri without the selection_required status. Always handle the callback defensively: verify that platform matches the platform you requested, check status before rendering selection UI, and fall back to a clear error state if selectionToken is missing when status is selection_required. The source does not specify the exact lifetime of selectionToken or additional callback parameter names beyond status, platform, and selectionToken, so do not hard-code a lifetime or depend on undocumented parameters.
Worked example: origin-modular GET request and redirect handling
Start by choosing the platform value and building the request URL as {{API_BASE_URL}}/v1/connect/{platform}. Add the x-access-key header with your token. Add redirectUri so the user returns to a known page after authorization, and add cancelRedirectUri if you need a distinct landing page for cancellation or denial; otherwise the user returns to redirectUri. For Instagram, add loginMethod only when you need to choose between instagram_login and facebook_login, remembering the linked Page requirement for facebook_login. For an Instagram reconnect, add reconnectAccountId only after validating the 24-hex pattern and confirming the account identity matches. For LinkedIn, Facebook, or Google Business with your own selection UI, add headless=true and prepare a callback handler that reads status, platform, and selectionToken. Add profileId only when the resulting integration must be associated with a profile in the same project, and add appId only when connecting under your own OAuth app for the same platform. After the call, check the status code first: on 200, read the required url string and redirect the user to it; on 500, read the required error string and show or log the failure. The worked example below shows the captured curl shape with the origin replaced by {{API_BASE_URL}}; adapt the platform and query values to your flow and keep the header name exact.
Response and failure matrix: 200 url, 500 error, cancel/deny fallback, selection_required
A 200 response returns a JSON object with a required url string. That URL is the next step for the user, so redirect to it exactly as returned and do not modify its query string. A 500 response returns a JSON object with a required error string. Treat any 500 as a failed attempt to obtain an OAuth URL: do not redirect the user to a stale or fabricated URL, and do not retry in a tight loop. The source specifies only the 200 and 500 response shapes for this endpoint, so do not invent additional status codes or error codes in your client. Cancellation and denial are not JSON responses: the user is redirected to cancelRedirectUri, or to redirectUri when cancelRedirectUri is omitted. Headless selection is also a redirect, not a JSON response: when status is selection_required, the callback to redirectUri carries platform and selectionToken for your selection UI. Invalid reconnect identity is a failure case to check before and after the call: validate reconnectAccountId against ^[a-fA-F0-9]{24}$ before sending, and if the reconnect does not complete, treat it as a failed connection rather than assuming existing posts were moved. The failure matrix below summarizes each case and the client action it requires.
| Field | Location | Type | Required | Notes |
|---|---|---|---|---|
| x-access-key | Header | string (token) | Yes | Authorization header; source contract name accessKey, wire header x-access-key, value <token>. |
| platform | Path | string | Yes | Enum: twitter | instagram | youtube | tiktok | pinterest | linkedin | bluesky | facebook | threads | googlebusiness. |
| loginMethod | Query | string | No | Instagram only. Enum: instagram_login | facebook_login. |
| reconnectAccountId | Query | string | No | Instagram reconnect. Pattern ^[a-fA-F0-9]{24}$. |
| redirectUri | Query | string | No | Format: uri. Final redirect after connection completes. |
| cancelRedirectUri | Query | string | No | Format: uri. Redirect on cancel or deny; falls back to redirectUri. |
| headless | Query | boolean | No | Default: false. True enables customer-owned selection UI. |
| profileId | Query | string | No | Must belong to the same project. Omit to connect without a profile. |
| appId | Query | string | No | Bring-your-own OAuth app id for the same platform. Omit for system app. |
| url | Response body (200) | string | Yes | OAuth URL to send the user to. |
| error | Response body (500) | string | Yes | Error message for a failed request. |
Contract parity draft; origin modularized as {{API_BASE_URL}}.
| Parameter | Type | Required | Enum / pattern / format / default | Rule |
|---|---|---|---|---|
| platform | string | Yes | twitter | instagram | youtube | tiktok | pinterest | linkedin | bluesky | facebook | threads | googlebusiness | Path parameter; choose one supported platform value. |
| loginMethod | string | No | instagram_login | facebook_login | Instagram only. facebook_login requires a linked Page; BYOK appId must reference a Facebook app. |
| reconnectAccountId | string | No | Pattern: ^[a-fA-F0-9]{24}$ | Instagram integration to reconnect. Account identity must match; existing posts are retained. |
| redirectUri | string | No | Format: uri | Final URL after connection completes. In headless mode also receives selection status query parameters. |
| cancelRedirectUri | string | No | Format: uri | Redirect on cancel or deny. Falls back to redirectUri when omitted. |
| headless | boolean | No | Default: false | True: redirect to redirectUri with short-lived selectionToken for customer-owned selection UI. False: hosted selection UI. |
| profileId | string | No | — | Profile to associate the resulting integration with. Must belong to the same project. |
| appId | string | No | — | Id of an OAuth app created via /v1/apps for the same platform. Omit to use the system app. |
Exact captured constraints preserved.
| Case | Signal | Client action |
|---|---|---|
| Success | 200 with required url string | Redirect the user to url exactly as returned. |
| Server failure | 500 with required error string | Show or log error. Do not redirect to a guessed URL. |
| User cancels or denies | Redirect to cancelRedirectUri, or redirectUri if cancelRedirectUri omitted | Render a cancelled state on that landing page; do not treat as a connected account. |
| Headless selection required | Redirect to redirectUri with status=selection_required, platform, selectionToken | Render your own selection UI using platform and short-lived selectionToken. |
| Invalid reconnect identity | reconnectAccountId fails ^[a-fA-F0-9]{24}$ or account identity does not match | Validate before sending; treat a failed reconnect as no connection and do not assume existing posts moved. |
Only 200 and 500 JSON shapes are specified in the source; no additional error codes invented.
curl -X GET "{{API_BASE_URL}}/v1/connect/twitter" \
-H "x-access-key: <token>"curl -X GET "{{API_BASE_URL}}/v1/connect/instagram?loginMethod=instagram_login&redirectUri=https%3A%2F%2Fexample.com%2Fcallback&cancelRedirectUri=https%3A%2F%2Fexample.com%2Fcancelled&headless=false" \
-H "x-access-key: <token>"{
"url": "string"
}{
"error": "string"
}| Scope | Field | Type | Type reference | Required | Description | Constraints |
|---|---|---|---|---|---|---|
| platform#1 | platform | string | __0 | Yes | kind: schemaValueIn; value: "twitter" | "instagram" | "youtube" | "tiktok" | "pinterest" | "linkedin" | "bluesky" | "facebook" | "threads" | "googlebusiness" | |
| loginMethod#2 | loginMethod | string | __0 | No | Instagram only. Facebook Login requires a linked Page; BYOK appId must reference a Facebook app. | |
| loginMethod#2 | loginMethod[variant1] | string | __0_extends:__1 | Instagram only. Facebook Login requires a linked Page; BYOK appId must reference a Facebook app. | kind: schemaValueIn; value: "instagram_login" | |
| loginMethod#2 | loginMethod[variant2] | string | __0_extends:__2 | Instagram only. Facebook Login requires a linked Page; BYOK appId must reference a Facebook app. | kind: schemaValueIn; value: "facebook_login" | |
| reconnectAccountId#3 | reconnectAccountId | string | __0 | No | Instagram integration to reconnect. Account identity must match; existing posts are retained. | kind: schemaMatch; value: ^[a-fA-F0-9]{24}$ |
| redirectUri#4 | redirectUri | string | __0 | No | Final URL to redirect to after the connection completes. In headless mode, this URL also receives selection status query parameters when customer-owned account selection is required. | kind: schemaFormat; value: uri |
| cancelRedirectUri#5 | cancelRedirectUri | string | __0 | No | URL to redirect to when the user cancels or denies the OAuth prompt. Falls back to redirectUri when omitted. | kind: schemaFormat; value: uri |
| headless#6 | headless | boolean | __0 | No | When true, platforms that require account selection redirect back to redirectUri with a short-lived selectionToken so you can build your own selection UI. When false, the service hosts the selection UI. | kind: schemaDefault; value: false |
| profileId#7 | profileId | string | __0 | No | Profile to associate the resulting integration with. Must belong to the same project. Omit to connect without a profile. | |
| appId#8 | appId | string | __0 | No | Connect under your own OAuth app (Bring Your Own Keys). Pass the id of an OAuth app created via /v1/apps for this same platform. Omit to use the service's system app. | |
| response#9 | response | object | __0 | |||
| response#9 | response.url | string | __1 | Yes | ||
| response#10 | response | object | __0 | |||
| response#10 | response.error | string | __1 | Yes |