X / Twitter White-label Setup
X setup is best approached as a deliberate paid-platform integration: get the app approved for your intended tier, wire the callback cleanly, and validate one branded OAuth flow before scaling out.
Fastest route to a first success: create the app in X Developer Portal, add the callback URL shown on this page, paste the credentials into UniPost, then connect one real test account before you expand scope or review work.
At a glance
| Question | Answer |
|---|---|
| Create the app in | X Developer Portal |
| UniPost credential card | X / Twitter |
| Client fields to copy | Client ID + Client Secret |
| Best for | Products that need customer X connections and are comfortable planning around X's tier and access constraints. |
| App review / approval | Access and feature availability are tier-dependent. Treat billing / plan approval as part of setup, not an afterthought. |
Before you start
- A company-owned X developer account with the intended paid access level.
- One test X account you control for the first branded connect.
- A rollout plan that accounts for X access limits and commercial constraints.
- An internal owner for credential rotation and developer-portal billing.
Callback URLs to whitelist
Copy these exactly into the platform developer console. Redirect mismatches are the fastest way to burn time during setup.
https://api.unipost.dev/v1/oauth/callback/twitterFirst working setup
1
Confirm the X developer access level before wiring code
If your developer access is not aligned with the rollout you want, no amount of callback tweaking will save the integration. Confirm the commercial and access prerequisites first.
2
Register UniPost's X callback in the developer portal
Add the callback URL below exactly as written. X OAuth setups are easy to derail with tiny environment mismatches, so treat the redirect URI as copy-paste material, not something to type from memory.
3
Paste the Client ID and Client Secret into UniPost
Use the X / Twitter credential row in UniPost's White-label Credentials screen. Save the credentials before testing, then retry from a clean browser session if you had earlier failures.
4
Run one full connect on a controlled X account
The first success goal is simple: the end user sees your X app branding during consent, and UniPost returns with a connected account rather than a plan or callback error.
5
Document access tier and owner details immediately
X integrations are operationally fragile if the billing owner, developer app owner, and engineering team are not aligned. Capture those details while the setup is fresh.
What to paste into UniPost
| X app field | UniPost field | Notes |
|---|---|---|
| Client ID | Client ID | Use the OAuth 2.0 client identifier from your X app. |
| Client Secret | Client Secret | Store once in UniPost, then manage future rotations like any production secret. |
| Callback / redirect URL | Callback URL below | Copy exactly to avoid redirect mismatch errors. |
Save the credentials first, then start a fresh connection attempt. Troubleshooting an OAuth flow against stale credentials usually creates false leads.
Connect an X account through your app
After your X app credentials are saved, prove the customer-facing flow your own app will use: create an API key, choose the branded profile, create a Connect session, send the returned OAuth URL to your end user, then confirm UniPost recorded the managed X account.
1
Step 1: create your first API key in the dashboard
Open UniPost in the same workspace where you saved the X / Twitter credentials, create an API key, and store it immediately. The first key must be created in the dashboard because there is no API key available yet to call POST/v1/api-keys.
2
Step 2: list profiles and copy the `profile_id` you will use for branding
Every workspace gets at least one profile. Start by listing profiles so you can grab the
id for the profile that should own your hosted Connect branding.3
Step 3: patch the profile branding that should show on hosted Connect
With the
profile_id in hand, update the logo, display name, and primary color. This is the fastest way to confirm your hosted Connect surface is reading your own branding instead of UniPost defaults.4
Step 4: create an X Connect session for your app user
From your backend, create a Connect session with
platform set to twitter, the branded profile_id, and your stable external_user_id. UniPost returns a hosted OAuth URL. Redirect your app user to that URL, or open it inside the connection flow in your own product, so they can authorize their X account under your white-label app.5
Step 5: confirm the managed X / Twitter account is visible through the API
After the user completes OAuth, UniPost stores the connected X account as a managed account tied to your
external_user_id. Verify it through the accounts API; the same user should also appear in the dashboard's Developer App Users view. If this call fails even after OAuth completes, re-check developer tier and app access before assuming the account list API is wrong.6
Step 6: use that managed account and profile in your first real API workflow
At this point you have the four values you need most often:
API_KEY, profile_id, external_user_id, and the connected X / Twitter account_id. From here, run a small end-to-end publish test so you know the white-label X connection is usable, not just visible.Common blockers
| Blocker | What to do about it |
|---|---|
| Tier mismatch | X problems often look like OAuth bugs when the real issue is access level or commercial eligibility. |
| Old browser session state | If you tested with the wrong credentials first, retry in a clean session after saving the correct app details. |
| Operational ownership | If one person's personal developer account owns production, future billing and rotation work becomes much harder. |
Definition of done
- The X consent screen shows your app branding.
- The redirect returns to UniPost successfully.
- A real X account is connected in the workspace.
- Your team has documented the owning developer account and access tier.