TikTok Ads · BYO Setup Guide

Set up your own
TikTok Marketing app.

This guide walks you through creating a TikTok Marketing API app that VelaReach will use to connect your TikTok For Business ad accounts — on your own credentials, your own rate limits, your own branded consent screen. Takes about 10 minutes of clicking, plus TikTok’s Marketing Partner review (1–4 weeks if you don’t already have access).

~10 min setup Medium 1–4 weeks review
✓
Use BYO if
  • · You already have TikTok Marketing Partner status from another tool
  • · You’re burning through the shared app’s daily request budget
  • · You need consent screens to display your own brand to clients
  • · Your compliance team requires an isolated app for TikTok data
✗
Stick with shared app if
  • · You don’t already have Marketing API access on your developer account
  • · You can’t wait 1–4 weeks for TikTok’s review
  • · You only manage a handful of ad accounts
  • · You want to be reporting on TikTok spend by lunch today

Before you begin

1

Sign in to the TikTok Developer Portal

Head to business-api.tiktok.com/portal and sign in with the same TikTok For Business account that owns your ad accounts. If this is your first time here, TikTok will ask you to accept the Developer Terms and link a Business Center.

https://business-api.tiktok.com/portal
♪ TikTok for Developers · Marketing API Portal
Welcome to TikTok Marketing API
Sign in with your TikTok For Business account to manage your developer apps.
Sign in with TikTok Documentation

The portal is separate from ads.tiktok.com — make sure you’re on the business-api subdomain.

ⓘ
Don’t have a Business Center yet? Create one at business.tiktok.com and add an ad account before continuing.
2

Apply for Marketing API access (if you don’t have it)

New developer accounts can’t create Marketing API apps until TikTok approves access. From the portal home, click Marketing API → Apply. You’ll fill in your company info, intended use case (“Connecting our TikTok ad accounts to VelaReach for reporting and automation” works fine), and an estimated request volume.

Approval takes 1–4 weeks. TikTok will email the address on your developer account when the decision lands. If you already see a My Apps tab in the sidebar, skip ahead to Step 3.

⚠
Marketing Partner status is a separate, longer review for high-volume agencies. Standard Marketing API access is enough for most VelaReach customers — you only need Partner status if you’re managing dozens of ad accounts and pushing the standard rate limits.
3

Create a Marketing API app

Once Marketing API access is live, click My Apps in the left sidebar, then Create New App. Name it something recognisable like VelaReach-YourCompanyName so it’s easy to identify on the consent screen.

https://business-api.tiktok.com/portal/apps/create
♪ TikTok for Developers · My Apps
↑ This is what your team will see on the OAuth consent screen.
Create

Pick a name your team will recognise — TikTok shows it on the consent screen.

4

Add the VelaReach redirect URL

This is the most common thing to get wrong, so copy carefully. On your new app’s detail page, scroll down to Advertiser redirect URL (sometimes labelled Callback URL). Paste this exact URL:

https://api.velareach.metaminds.store/api/v1/integrations/tiktok/callback
https://business-api.tiktok.com/portal/apps/1738373141733378/edit
VelaReach-Acme · App settings
● Ad Account Management   ● Reporting   ● Audience Management
↑ Paste the exact URL above. No trailing slash, HTTPS only.
Save changes

TikTok matches the redirect URL character-for-character. No trailing slash.

⚠
90% of BYO failures happen here. If OAuth later returns “redirect_uri does not match”, come back and re-paste using the Copy button. Watch out for invisible whitespace if you typed it manually.
5

Copy your App ID and Secret

Save the app, then scroll to the top of the same page. You’ll see two fields near the header: App ID (a long numeric value) and Secret (a 64-character hex string).

https://business-api.tiktok.com/portal/apps/1738373141733378
VelaReach-Acme · App credentials
↑ Numeric ID — do NOT paste the app name here.
Show ↑ Click Show to reveal the 64-char secret.
● Live · Marketing API enabled

App ID is the numeric value at the top — not the app’s display name.

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

Paste credentials into VelaReach

Back in VelaReach: Settings → Integrations → click the TikTok 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 App ID and Secret from the previous step.

Click Test & save. VelaReach makes a live call to the TikTok Marketing API with your credentials and runs 5 validation checks inline.

7

Verify the live test passes

You should see green check marks next to:

  • · Credentials format — App ID is numeric and Secret is 64 hex chars
  • · Redirect URL whitelisted — matches your TikTok app settings
  • · App exists on platform — TikTok returned your app’s name and status
  • · Marketing API enabled — the app has the right product attached

Click Reconnect now → to run the OAuth flow through your new app. The TikTok Business Center consent screen will display your app name and the scopes it’s requesting.

8

Let VelaReach handle token refresh

TikTok access tokens expire after 24 hours, which is much shorter than most ad platforms. Don’t worry — VelaReach refreshes them automatically using the long-lived refresh token TikTok issues alongside. You’ll never see a “please reconnect” banner unless you revoke the app from Business Center.

ⓘ
The first sync after reconnecting can hit TikTok’s aggressive initial-sync rate limits. VelaReach will retry with exponential backoff — expect the first historical pull to take 10–30 minutes.

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

“40105 — auth code invalid or expired”
TikTok auth codes are valid for only 60 seconds. If you sat on the consent screen too long, or your laptop went to sleep mid-flow, the code expired before VelaReach could redeem it. Click Reconnect again and complete the consent screen quickly — it should work the second time.
“app_id must be provided” or “invalid app_id”
You pasted the app’s display name (VelaReach-Acme) instead of the numeric App ID. Open the app detail page in the TikTok portal, copy just the long numeric value at the top of the page (looks like 1738373141733378), and try again.
“Permission denied: Marketing Partner status required”
Some scopes — particularly creative upload and audience management — require TikTok Marketing Partner status, not just standard Marketing API access. To check, open your app in the developer portal: if scopes appear greyed-out with a lock icon, you need Partner approval. Apply at the Marketing Partner page; review takes another 2–6 weeks. Reporting-only use cases don’t need Partner status.
HTTP 429 — rate limit exceeded during first sync
TikTok throttles the very first historical pull aggressively (sometimes 10 requests/minute for new apps). VelaReach automatically backs off and retries — the first sync may take 10–30 minutes to complete. After that, your app warms up and the rate limit relaxes. If 429s persist for over an hour, contact support and we’ll look at TikTok’s headers together.
I want to revert to the shared VelaReach app
In the BYO wizard (or the Advanced tab of the Manage drawer), click Remove BYO. VelaReach wipes the encrypted credentials, flips back to the shared app, and revokes your app’s active tokens. Historical data stays. Click Reconnect once more to mint fresh tokens via the shared app.
💬
Stuck? Email us — we’ll hop on a 15-min screen share.
TikTok’s developer portal is one of the more confusing ones — we don’t expect every customer to nail it the first try. Email support@velareach.com with your workspace name + exact error and we’ll pair with you.