Skip to main content
X Ads · BYO Setup Guide

Set up your own
X Ads API app.

This guide walks you through creating an X (formerly Twitter) developer app and wiring it to VelaReach. The technical setup is about 10 minutes, but X Ads API access also requires a separately-approved Ads API application on your X developer account before any of this will work.

~10 min setup Expert Approval required
⚠
Read this before you start
X Ads API access requires a separately-approved Ads API application on your X developer account — this is a manual review step on top of whichever X API access tier you’re on (Free, Basic, Pro, Enterprise, or the new pay-per-use model). If your Ads API application hasn’t been approved yet, BYO is not going to help — you still won’t be able to query ads data via the API. Review the options at developer.x.com/en/products/x-api/enterprise before proceeding with this guide.
✓
Use BYO if
  • · Your Ads API application has already been approved by X
  • · You want OAuth consent screens to display your own brand
  • · You need API request quota independent of VelaReach’s shared app
  • · Your security team requires tokens to live in your own developer account
✗
Stick with shared app if
  • · You haven’t applied for (or been approved for) Ads API access yet
  • · Your Ads API application is still under review
  • · You only need to read X data occasionally for reporting
  • · You want to be connected in the next 60 seconds

Before you begin

1

Verify you have Ads API access

Sign in to developer.x.com/en/portal/products. Your current X API access plan is shown at the top of the page, and below it the list of add-on products. On the Ads API row you should see Approved rather than Apply.

https://developer.x.com/en/portal/products
𝕏 Developer Platform · Products
Your access plan
● Active X API plan
Includes: v2 API, Ads API add-on (approved)
Add-on products
📊 Ads API
● Approved — full read & write access

If the Ads API row doesn’t say “Approved”, stop here and submit the application first.

⚠
If you see “Apply” instead of “Approved” on the Ads API row, click it and submit the application form. X reviews these manually and approval can take 2–4 weeks. There’s no point continuing this guide until that’s done.
2

Create a Project in the Developer Portal

X organises everything into Projects, which contain Apps. From the dashboard, click Projects & Apps in the left sidebar, then + New Project. Name the project something recognisable like VelaReach-YourCompanyName, choose Making a bot or Building tools for businesses as the use case, and write a short description.

https://developer.x.com/en/portal/projects/new
𝕏 Developer Platform · New Project
Next →

Projects group your Apps and inherit the Ads API access from your tier.

3

Create an App inside the Project

On the project setup screen, click + Add App. Give it a name (X requires this to be globally unique — if VelaReach-Acme is taken, try VelaReach-Acme-Prod). X will immediately show you a one-time set of API keys — you can ignore those for now since BYO uses OAuth 2.0, not API keys.

4

Enable OAuth 2.0 in User authentication settings

Open your new App and click User authentication settings → Set up. This is where you turn on OAuth 2.0 (the modern flow VelaReach uses) and tell X about the redirect URL.

Set App permissions to Read and write. Set Type of App to Web App, Automated App or Bot.

https://developer.x.com/en/portal/projects/.../apps/.../settings
VelaReach-Acme · User authentication settings
● Enabled
● Read and write
● Web App, Automated App or Bot
↑ Paste the exact URL above. No trailing slash, HTTPS only.
Save

You must enable OAuth 2.0 explicitly — the older OAuth 1.0a flow is not what VelaReach uses.

5

Add the VelaReach redirect URL

On the same authentication settings page, find the Callback URI / Redirect URL field and paste this exact URL:

https://api.velareach.metaminds.store/api/v1/integrations/x/callback

Also fill in the Website URL field (X requires it — https://velareach.metaminds.store works fine). Click Save.

⚠
90% of BYO failures happen here. If OAuth later returns “Callback URL not approved for this client application”, come back and re-paste using the Copy button. X is strict about trailing slashes and protocol.
6

Confirm the OAuth 2.0 scopes

OAuth 2.0 scopes are not configured per-app on X — they’re requested at the time of the OAuth flow. VelaReach will request the following scopes when the user consents, and X will display them on the approval screen:

  • · ads.read — read campaign and creative metadata
  • · ads.write — create and update campaigns (for automation rules)
  • · tweet.read — required by X to access ad post content
  • · users.read — identify the connecting user
  • · offline.access — issue a refresh token so we can renew without re-prompt
ⓘ
If your X tier doesn’t include Ads API, the ads.read scope will be silently stripped from the issued token. The validation step in VelaReach will catch this.
7

Copy your Client ID and Client Secret

Open the Keys and tokens tab on your App. Scroll down to the OAuth 2.0 Client ID and Client Secret section. Click Regenerate if this is your first time and you don’t see a secret — X only shows the secret once, immediately after generation.

https://developer.x.com/en/portal/projects/.../apps/.../keys
VelaReach-Acme · Keys and tokens
↑ Base64-style, ends in “:1:ci” for confidential clients.
Reveal ↑ Shown only once. Save it now.
[ Not used by VelaReach ]

Save the secret immediately — X will not show it again. If you lose it, you must regenerate.

🔒
Treat the Client Secret like a password. VelaReach encrypts it with AES-256-GCM the moment you submit, and never writes it to logs.
8

Paste credentials into VelaReach and reconnect

Back in VelaReach: Settings → Integrations → click the X Ads card → Manage → Advanced tab → Set up BYO app. The 4-step wizard opens. Click past Intro and Guide, then on Step 3 paste the Client ID and Client Secret from the previous step.

Click Test & save. VelaReach makes a live call to the X API with your credentials and runs 5 validation checks inline. You should see green check marks across the board, then click Reconnect now → to run the OAuth flow.

ⓘ
X uses PKCE for OAuth 2.0 — VelaReach handles the code_challenge/code_verifier dance automatically. You don’t need to configure anything. X-issued tokens last 365 days, so refreshes are rare.

After reconnecting, what changes?

✓ Preserved
  • · All historical spend, impressions, and ROAS data
  • · Your picker selection (which ad accounts are tracked)
  • · Automation rules and budget pacing configs
  • · Scheduled reports and Slack notifications
  • · Every tag, filter, and saved view
✦ Changed
  • · OAuth tokens revoked and re-minted via your app
  • · Card shows violet BYO app pill
  • · Consent screen on future reconnects displays your app name
  • · Audit log records who switched and when
  • · API calls count against your app’s rate limits

Troubleshooting

“Your App is not set up for Ads API access”
Your developer account hasn’t been approved for the Ads API add-on. Ads API is a separate application that must be approved by X on top of whichever X API access plan you’re on. Open developer.x.com/en/portal/products and check the Ads API row — if it says “Apply”, submit the form and wait for approval (typically 2–4 weeks). There’s no point continuing BYO setup until that’s done.
“invalid_client” from the X token endpoint
Almost always a bad Client Secret. The most common cause: you copied a hidden character (zero-width space, soft hyphen) when pasting from the X portal. Go back to the Keys and tokens tab, click Regenerate next to the OAuth 2.0 Client Secret, and paste the new value into VelaReach. The old secret will stop working immediately.
“code_challenge missing” or PKCE error
VelaReach generates the code_challenge automatically, so this error usually means the OAuth flow was tampered with by a browser extension or proxy. Try the Reconnect flow in an incognito window with extensions disabled. If it works there, an extension on your normal profile (often a privacy or anti-tracker tool) is stripping the code_challenge query parameter mid-redirect.
“Callback URL not approved for this client application”
The redirect URL on the X User authentication settings page doesn’t exactly match what VelaReach is sending. Open the App in the X portal, click User authentication settings, and re-paste using the Copy button above. Watch for trailing slashes, http vs https, and accidental whitespace.
I have an old v1.1 Twitter app — can I reuse it?
No. Old v1.1 apps don’t support OAuth 2.0 with PKCE, which VelaReach requires. You need to create a new App inside a Project on the modern X Developer Portal (Step 2–3 of this guide). Your old API keys can keep running their existing integrations — they won’t conflict.
💬
Stuck? Email us — we’ll hop on a 15-min screen share.
X Ads is the most advanced BYO setup we offer because of the Ads API approval gate. Email support@velareach.com with your workspace name + exact error and we’ll pair with you. We can also help you frame the Ads API application so X is more likely to approve it on the first try.