A plain-language overview of the access we'll request, what we read, who on your team should connect, and what to expect during setup.
This page covers X Ads, which brings in the media library of your X ads accounts. To sync your brand account's own organic posts, use the separate X integration described in X (Twitter) — Authentication. The two integrations connect independently and authorize differently, as explained below.
What to expect
Connecting takes a couple of minutes. When you connect X Ads in Medialake, you're redirected to the official X authorization screen. You approve it yourself and can revoke access at any time. We never see or store your password: the login happens entirely on x.com, and once you approve you're returned to Medialake.
X Ads is a paid-media integration. Medialake reads the media library of your X ads accounts (the images, videos, and GIFs uploaded for your ad campaigns) through the official X Ads API. We never create, change, or delete campaigns, ads, or media, and we never spend anything.
The X Ads API only accepts OAuth 1.0a, so this integration uses X's three-step OAuth 1.0a sign-in rather than the OAuth 2.0 sign-in used by the organic X integration:
You Medialake X │ connect source │ │ │────────────────────────▶│ │ │ │ request token │ │ │────────────────────────▶│ │ │◀────────────────────────│ │ redirect to X │ │ │◀────────────────────────│ │ │ sign in & authorize │ │ │──────────────────────────────────────────────────▶│ │ redirect with verifier │ │ │◀──────────────────────────────────────────────────│ │ │ exchange for tokens │ │ │────────────────────────▶│ │ │ access token + secret │ │ │◀────────────────────────│ │ source authorized │ │ │◀────────────────────────│ │
Two ways to connect
X Ads can be connected through Medialake's OAuth app or through your own X developer app:
Medialake's OAuth app (default). Accounts connect using Medialake's central X Ads app. No setup is required: just sign in and approve.
Your own app (optional). If your organization would rather own the app that appears on X's authorization screen, you can use an app from your own X developer account and add its keys to Medialake. Your organization owns the app and can disable it at any time.
What Medialake reads, and everything else on this page, is identical for both options.
Setting up your own app (optional)
Most accounts connect with Medialake's OAuth app and can skip this section.
In the X Developer Console, create an app, or choose an existing one. Give it a name your team will recognize, because this is the name shown on X's authorization screen.
Apply for Ads API access for that app using X's Ads API Access Form. X reviews each request before granting access. Medialake reads the media library, which is part of X's Creatives endpoints, so the app needs Standard Access, which includes Creatives. Conversion Only access does not.
Add Medialake's callback URL to the app's callback URL allowlist. X requires an exact match:
https://oauth2.medialakeapp.com/xads-redirect
Set the app's permission level to read only. Medialake only sends read requests, so it needs neither write nor Direct Message access. If you change the level later, reconnect so that X issues a token with the new level.
Copy the app's API Key and API Key Secret (also called the consumer key and consumer secret). X shows them only once.
>Keep the API Key Secret private. Store it in an approved password manager or secret-management system. Do not email it, paste it into a support ticket, or commit it to source control.
Add your app's keys to Medialake
You need Medialake administrator privileges for this step.
Open Administration → Integrations from the sidebar.
Open the X Ads integration.
In the Access Keys section, click Create New Setting.
In the New access key panel, give the key a Name, for example
Marketing X Ads app. Team members see this name when they choose an app to connect with.Under Credentials, fill in both fields:
- X app API Key (consumer key) with Ads API access: your app's API Key.
- X app API Key Secret (consumer secret) with Ads API access: your app's API Key Secret.
Under Who can use it?, choose which teams can connect accounts with this key, or allow all teams.
Click Save access key.
The values are stored encrypted and are never shown again.
Connect and choose what to sync
Any team member who is allowed to connect sources can do this.
Open Connections → Catalogue from the side menu.
Find X Ads and click Connect.
Under How do you want to connect?, choose Connect it myself: "Sign in with your X Ads account and approve what Medialake can access."
If your organization has saved its own app as an access key, an OAuth app dropdown also appears. Leave it on Medialake's OAuth app (tagged Recommended), or pick your organization's app by the name it was saved under.
Sign in to x.com, check the account shown, and authorize the app. You're returned to Medialake.
Choose what to sync. Every ads account the signed-in user can access is listed by its name followed by — Media Library, for example Your Company — Media Library. Select one or more.
Medialake names the new connection after the signed-in account's @handle. One connection can cover several ads accounts.
For each selected ads account, Medialake syncs the images, videos, and GIFs in its media library. GIFs come in as MP4 videos, because that is how X stores them. Media that X is still processing is skipped until it is ready, and is picked up on a later sync. X Ads does not bring in campaigns or performance metrics.
Verifying it's really us
On X's authorization screen, check that the app requesting access is the one you expect: Medialake's X Ads app, or the app your organization created and named. If the name doesn't match, stop and contact us. Never approve an X access request you weren't expecting.
Who should do the connecting
This works differently from the organic X integration, which has to be authorized while signed in as the brand account itself. For X Ads, approve the connection while signed in to x.com as any user who has access to the ads accounts you want to sync: the ads account owner, or a user the owner has given access to the ads account at business.x.com.
After connecting, Medialake lists every ads account that user can access. Ads accounts whose media library the user is not allowed to read are left out of the list.
In practice, the person connecting needs:
The login for an X account with access to your ads accounts, and
Access to that account's two-factor authentication or email inbox, since X may send a verification code during sign-in.
Choose an account that will keep its access. If it loses access to an ads account, Medialake can no longer sync that account's media library and someone will need to reconnect with an account that has access.
What Medialake reads
With OAuth 1.0a, X does not ask you to approve individual scopes. The token carries the permission level set on the app itself in X's developer settings, and X's authorization screen describes what that level allows. Whatever the app's level, Medialake's use is limited to these read requests:
What we read | How we use it |
Your ads accounts: ID, name, and time zone | To list them as sources you can choose, and to suggest a region for each one |
The media library of each selected ads account | To bring ad images, videos, and GIFs into Medialake |
The signed-in account's profile basics: ID, name, @handle, and profile photo | To confirm which account connected, and to name the connection |
What Medialake can and cannot do
Medialake does not, and cannot:
See or store your password, or log in as you on x.com
Reach any ads account the signed-in user cannot access
Medialake only sends read requests. It never:
Creates, edits, pauses, or deletes campaigns, ads, or ad media
Spends money or changes any billing or funding settings
Posts, replies, likes, reposts, or follows
Reads or sends Direct Messages
Changes any account or security settings
Staying connected
X Ads tokens do not expire, so there is no renewal to plan around and nothing to re-approve on a schedule. They stay valid until access is revoked or X suspends the app.
If X ever rejects the token, Medialake confirms it with X and stops syncing the source until someone connects it again from Connections → Catalogue. That happens if the app's access is revoked on x.com, or if your own app's API Key and Secret are regenerated. In that last case, save the new values as an access key in Medialake before you reconnect.
Revoking access
You're in control at any time. To remove Medialake:
On x.com, signed in as the account that connected, open the Apps and sessions section of your account settings, select the app, and revoke its access, or
Disconnect the X Ads source in Medialake.
Revoking on X invalidates the tokens and data collection stops without any action needed from us.
Troubleshooting
Symptom | What to check |
X shows an error instead of the authorization screen (own app) | The callback URL |
"X Ads request token expired, please restart the connection" | More than 15 minutes passed between starting the connection and authorizing on X. Start again from Connections → Catalogue. |
"This connection link is invalid or has expired. Please start the connection again." | The authorization screen was left open too long, or the link was already used. Start again from Connections → Catalogue. |
The wrong account connected | You were signed in to a different X account when you authorized. Check the account shown on X's authorization screen, sign in as the right one, and connect again. |
An ads account you expected is missing | The signed-in user has no access to it, or isn't allowed to read its media library. Ask the ads account owner to grant access at business.x.com, then reconnect. |
Some media didn't sync | Media that X is still processing is skipped until it is ready. Files in formats Medialake doesn't support are also skipped. |
A working connection stopped syncing | Access was revoked on x.com, or your own app's keys were regenerated. Reconnect, and update the access key first if the keys changed. |
If you get stuck, contact [email protected]. Do not include your API Key Secret.
Further reading (X documentation)
X Ads API introduction: what the Ads API is and how to apply for access
Getting started with the X Ads API: developer apps, Ads API access levels, and keys
Making authenticated requests: the OAuth 1.0a method the Ads API requires
Accessing ads accounts: how ads account access is granted to users
You can review or withdraw access at any time from your X account's connected apps settings.
