Use your own X app

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. 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

Create the developer account and the app

Sign in at 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.

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.

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.

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.

Connect an account

Call POST /v1/accounts/connect with "platform": "twitter", as in Connect an X account.

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.

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.

X / Twitter API: capabilities, limits, and scopes
Platform apps: which platforms use SocialAPI’s app and which use yours
Connect accounts: the shared connect flow
Errors: every error code

​Before you start

​Set up the app

​Use a different app for one brand

​Replace the client secret

​Troubleshooting

​Related

Before you start

Set up the app

Use a different app for one brand

Replace the client secret

Troubleshooting

Related