Get social network authentication URL

Generate an OAuth authentication URL for connecting a social media account.

Generate an OAuth authentication URL for connecting a social media account. This endpoint returns a URL that you should redirect users to in order to authenticate and authorize your application to access their social media account.

Prerequisites:

  • The social network must be configured for your organization using the POST /v1/social-networks endpoint
  • You must have valid OAuth credentials (client_key and client_secret) stored for the specified network

Workflow:

  1. Ensure the social network is configured for your organization
  2. Call this endpoint to get the authentication URL (optionally include tenant_id to associate accounts with your end-users)
  3. Redirect the user to the returned auth_url
  4. The user will authenticate on the social network's platform
  5. The user will be redirected back to your specified redirect_uri (or default)
  6. Handle the OAuth callback to complete the account connection

Tenant ID: Optionally provide a tenant_id to associate the connected social account with a specific tenant/customer in your system. This enables filtering social accounts by tenant using GET /v1/social-accounts?tenantId=xxx. The tenant_id must contain only alphanumeric characters, underscores, and hyphens.

Redirect URI: If you provide a redirect_uri in the request body, it is the final application destination after Outstand completes the connection, not the OAuth callback registered with the provider. For YouTube BYOK, configure oauth_callback_url on the credential separately. If redirect_uri is omitted, the user returns to the Outstand dashboard.

Connecting multiple accounts on the same network: Most networks skip the authorization screen and silently re-use the account already signed in on the user's browser session. That means a user connecting their second account can end up re-authorizing the first one, with logging out of the network as the only workaround. Set force_account_selection: true to always show the authorization / account-selection screen. It is honoured by tiktok, facebook, instagram, youtube and google_business, and ignored by networks that expose no equivalent, so it is safe to send on every request.

Instagram Direct Messages: Messaging access is not requested by default. To use the Conversations API, set scopes to instagram_business_basic,instagram_business_content_publish,instagram_business_manage_comments,instagram_business_manage_insights,instagram_business_manage_messages. Custom scopes replace the defaults, so keep the first four unless you deliberately want a messaging-only connection. Accounts connected without instagram_business_manage_messages do not receive DMs and must be reconnected with it.

Important: For white-label users, this is a very important endpoint as it guarantees your customers never see our branding in the authentication flow.

POST/v1/social-networks/{network}/auth-url

Path Parameters

networkstring

Request Body

redirect_uri?string

Optional redirect URI for successful OAuth callback. If not provided, a default redirect URI will be used - which redirects in our management dashboard. The redirect URI usually is used to redirect somewhere in your own application to continue the user journey.

Formaturi
tenant_id?string

Optional customer-provided tenant identifier. This will be associated with any social accounts created during this OAuth flow, enabling you to filter accounts by tenant later using the GET /v1/social-accounts endpoint.

scopes?string

Optional comma-separated list of OAuth scopes to request for this network. When provided, ONLY these scopes are requested, overriding the defaults. When omitted, the default scopes for the network are used. Useful when bringing your own OAuth keys and your app only has a subset of products or permissions enabled. Instagram Direct Messages are opt-in: the default Instagram scopes (instagram_business_basic, instagram_business_content_publish, instagram_business_manage_comments, instagram_business_manage_insights) do not include instagram_business_manage_messages, so to use the Conversations API pass all four defaults plus instagram_business_manage_messages here. Accounts connected without it receive no DMs and must be reconnected with it.

force_account_selection?boolean

Optional. When true, the OAuth flow always shows the network's authorization / account-selection screen instead of silently re-using the account already signed in on the user's browser session. Set this when your users connect more than one account on the same network - otherwise the second connection can silently re-authorize the first account and the user has to log out of the network to switch. Honoured by tiktok (disable_auto_auth), facebook (auth_type=reauthenticate), instagram (force_reauth), youtube and google_business (prompt=select_account). Networks with no equivalent (linkedin, x, pinterest, threads, vimeo, bluesky) ignore it, so it is safe to send unconditionally.

Response Body

const body = JSON.stringify({})fetch("https://api.outstand.so/v1/social-networks/string/auth-url", {  method: "POST",  headers: {    "Content-Type": "application/json"  },  body})
{
  "success": true,
  "data": {
    "auth_url": "https://www.outstand.so/app/api/socials/instagram/:orgId?state=..."
  }
}
{
  "success": false,
  "error": "Invalid payload",
  "details": {
    "network": {
      "_errors": [
        "Required"
      ]
    }
  }
}
{
  "success": false,
  "error": "Invalid payload",
  "details": {
    "network": {
      "_errors": [
        "Required"
      ]
    }
  }
}
{
  "success": false,
  "error": "Internal server error",
  "message": "Database connection failed"
}