> ## Documentation Index > Fetch the complete documentation index at: https://docs.social-api.ai/llms.txt > Use this file to discover all available pages before exploring further. > ## Agent Instructions > Base URL: https://api.social-api.ai/v1. Send your API key in the Authorization header: Authorization: Bearer . > Every error response from /v1 is JSON: { "error": { "code", "message", "meta" (optional) }, "request_id" }. Branch on error.code; use error.message only for logs. > A 429 response carries a Retry-After header, in seconds, when the limit has a known wait. > Paginated list endpoints return next_cursor, at the top level or inside pagination (see /guides/pagination). Pass it as the cursor query parameter to get the next page. An absent or empty next_cursor means you have the last page. > Treat every ID as an opaque string: do not parse it or assume a format. > Support differs by platform and by operation. Check /platforms/overview before assuming an operation works on a platform. An unsupported operation returns 501 with error.code resource.not_supported. # Use your own X app > Create an X developer app, save its OAuth 2.0 credentials in SocialAPI, and connect X accounts, with the exact settings and fixes for common errors. Connecting X to SocialAPI needs an X developer app that you create. SocialAPI has no shared X app, because X bills API usage to the developer account that owns the app, in pay-per-use credits, and X's free API tier is closed to new developer accounts. Every read and write on your X accounts is billed to your X developer account. See [Why X uses your own app](/guides/platform-credentials#why-x-uses-your-own-app). SocialAPI uses the app's OAuth 2.0 Client ID and Client Secret. When you create the app, X first shows a Bearer Token and OAuth 1.0 keys (Consumer Key, Access Token). SocialAPI does not use them. The OAuth 2.0 Client ID and Client Secret appear only after you finish step 2. ## Before you start * An X account with a verified email address and phone number. * A payment method for X pay-per-use credits. X sells no free tier to new developer accounts. * Access to the SocialAPI dashboard. Saving X credentials is a dashboard action: no API endpoint saves them. ## Set up the app **1. Create the developer account and the app** Sign in at [console.x.com](https://console.x.com) with your X account and accept the Developer Agreement. Describe your use case, add a payment method, and buy credits. Create a Project, then create an App inside it. X shows each credential once. Copy it when it appears, because X issues a new one instead of showing it again. **2. Set up user authentication** Open the app, find **User authentication settings**, and click **Set up**. Set all of these on the same form: * **App permissions:** Read and write and Direct message. * **Type of App:** Web App, Automated App or Bot. Both give the app a Client Secret. * **Callback URI / Redirect URL:** `https://api.social-api.ai/oauth/callback/twitter`. It must match exactly, with no trailing slash. * **Website URL:** your own site, or `https://social-api.ai`. Click **Save**. SocialAPI requests these scopes from each person who connects: `tweet.read`, `tweet.write`, `tweet.moderate.write`, `users.read`, `dm.read`, `dm.write`, `like.write`, `media.write`, and `offline.access`. The app permissions above let X grant them. Changing the app permissions later means each person reconnects. **3. Copy the OAuth 2.0 credentials** After you save, an **OAuth 2.0** section appears in the app. Copy the **Client ID** and the **Client Secret**. Store the secret somewhere safe. **4. Save the credentials in SocialAPI** In the SocialAPI dashboard, open **Settings** > **Integrations** > **Twitter integration**. Under **Default credentials**, click **Add credentials**. Paste the Client ID and the Client Secret, click **Test credentials** to check them with X, then click **Save and continue**. SocialAPI never returns the Client Secret from any endpoint. It shows only the start of the Client ID. **5. Connect an account** Call `POST /v1/accounts/connect` with `"platform": "twitter"`, as in [Connect an X account](/platforms/twitter#connect-an-account). ```bash theme={null} curl -X POST https://api.social-api.ai/v1/accounts/connect \ -H "Authorization: Bearer $SOCAPI_KEY" \ -H "Content-Type: application/json" \ -d '{ "platform": "twitter", "redirect_uri": "https://app.example.com/oauth/callback", "state": "session_abc123" }' ``` Send the person to the returned `auth_url`. Without saved credentials, `POST /v1/accounts/connect` returns `412 byok.credentials_missing`. ## Use a different app for one brand Save a second X app for a single brand, for example one client's brand in an agency account, from the same dashboard page. Under **Brand overrides**, click **Override** on the brand's row, paste that app's Client ID and Client Secret, then click **Save and continue**. A brand with its own app connects through that app. Every other brand uses your default app. Click **Remove** on the brand's row to return that brand to the default. ## Replace the client secret After you regenerate the Client Secret in X, click **Rotate** under **Default credentials**, or on the brand's row under **Brand overrides**, and save the new secret the same way as in step 4. Until you do, a new connection ends on your redirect URI with `error=byok.credentials_invalid`. ## Troubleshooting > **Test credentials fails, or connecting ends with error=byok.credentials\_invalid** > > X rejected the saved Client ID and Client Secret. Check that you pasted the OAuth 2.0 **Client ID** and **Client Secret** from the app's **OAuth 2.0** section, not the Consumer Key, the API Secret, or the Bearer Token that X shows when you create the app. If you regenerated the secret in X, save the new one. > **POST /v1/accounts/connect returns 412 byok.credentials\_missing** > > No X app is saved for the brand and no default is saved. Save the credentials as in step 4, then connect again. > **Connecting ends with error=byok.app\_access\_denied** > > X refused your app access to its API. The app's access level on X does not allow the call. Check your X developer account, its credits, and the app's access level in the X Developer Console. > **X shows a callback URL mismatch** > > The callback URL on your X app differs from the one SocialAPI sends. Set it to `https://api.social-api.ai/oauth/callback/twitter` exactly, with no trailing slash and no extra path. > **The connection works but calls return 403 platform.twitter.insufficient\_scope** > > The app permissions on X are lower than Read and write and Direct message, or the account connected before you raised them. Set the permissions as in step 2, then reconnect the account. See [Reconnect an account](/guides/connect-accounts#reconnect-an-account). > **Calls return 402 platform.twitter.usage\_capped** > > Your X developer account is out of credits or reached its spending limit. Add credits or raise the spending limit in the X Developer Console. > **Calls return 429 platform.twitter.rate\_limit** > > X's own rate limit applies to each connected account. Wait, then retry. SocialAPI's own limits are in [Rate limits](/guides/rate-limits). ## Related * [X / Twitter API](/platforms/twitter): capabilities, limits, and scopes * [Platform apps](/guides/platform-credentials): which platforms use SocialAPI's app and which use yours * [Connect accounts](/guides/connect-accounts): the shared connect flow * [Errors](/guides/errors): every error code This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.