> ## Documentation Index
> Fetch the complete documentation index at: https://docs.markifact.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Custom X Ads App

> Connect X Ads through your own X app (white-label) by pasting your API key, API key secret, access token, and access token secret.

Markifact supports two ways to connect X Ads: using the built-in **Markifact app** (Quick Connect) or connecting through your own **X app** (Custom App). With a custom app, every request Markifact makes to the X Ads API runs under your app, so your clients never see Markifact in their connected apps.

<Note>
  Custom app connections are available on the **Team** plan. See [White-label Connections](/core-concepts/white-label-connections) for the overview.
</Note>

***

## Quick Connect vs Custom App

| Feature                 | Quick Connect        | Custom App                             |
| :---------------------- | :------------------- | :------------------------------------- |
| **Setup Time**          | 1 minute             | 20-30 minutes, plus X's Ads API access |
| **App the client sees** | Markifact            | Yours                                  |
| **API rate limits**     | Markifact's app      | Your app                               |
| **White Label**         | No                   | Yes                                    |
| **Plan**                | All plans            | Team                                   |
| **Best For**            | Quick setup, testing | Agencies, strict client requirements   |

***

## What You Need

Four values, because the X Ads API uses OAuth 1.0a rather than OAuth 2.0. The **API key pair** identifies your app and the **access token pair** identifies the user, and every request is signed with a combination of the two.

| Value                   | Where it comes from                                                                                         |
| :---------------------- | :---------------------------------------------------------------------------------------------------------- |
| **API Key**             | Your app's **Keys and tokens** tab in the [X developer portal](https://developer.x.com/en/portal/dashboard) |
| **API Key Secret**      | The same tab                                                                                                |
| **Access Token**        | Generated on the same tab for the user who has access to the ad accounts                                    |
| **Access Token Secret** | Generated together with the access token                                                                    |

<Warning>
  All four values must come from the **same app**. An access token generated under a different API key cannot be signed with this one, and X rejects the request. There is nothing to refresh: OAuth 1.0a tokens stay valid until the user revokes the app.
</Warning>

<Note>
  **Already have your own authorization flow?** If your systems already hold an access token pair issued by your app, skip to [Connect to Markifact](#connect-to-markifact).
</Note>

***

## Setting Up Your Custom X Ads App

<Steps>
  <Step title="Create the App">
    1. Open the [X developer portal](https://developer.x.com/en/portal/dashboard) and create a project and an app inside it
    2. Enter the app name. This is the branding users see when they authorize
    3. Under **User authentication settings**, turn on OAuth 1.0a, set **App permissions** to **Read and write**, and enter a callback URL you control (for example `https://www.youragency.com/x-callback`) and your website URL
  </Step>

  <Step title="Request Ads API Access">
    The Ads API is not available to every app. Apply for X Ads API access for your developer account and wait for approval. Agencies that already run their own integrations will have this in place; until it is granted, the accounts endpoint returns authorization errors.
  </Step>

  <Step title="Copy the API Key Pair">
    Open the app's **Keys and tokens** tab and copy the **API Key** and **API Key Secret** (shown once when generated; regenerate if you lost them).
  </Step>

  <Step title="Generate the Access Token Pair">
    On the same tab, under **Access Token and Secret**, click **Generate**. The tokens are created for the X account you are signed in as, so sign in as the user who has access to the ad accounts you want to manage.

    Copy the **Access Token** and **Access Token Secret**. Make sure the permissions shown next to them say **Read and Write**; if they say Read only, fix the app permissions first and regenerate.

    > **Important:** Keep these values secure. Anyone holding all four can act on every ad account the user can reach.
  </Step>

  <Step title="Connect to Markifact">
    1. In Markifact, go to the [Connections](https://app.markifact.com/connections) page
    2. Click **Connect** on **X Ads**
    3. Select the **Custom App (White-label)** tab
    4. Enter a **Connection Name** (for example "Acme Agency X Ads")
    5. Paste your **API Key**, **API Key Secret**, **Access Token**, and **Access Token Secret**
    6. Click **Verify & Connect**

    Markifact makes one signed call that lists the ad accounts the tokens can reach. Nothing is saved unless it succeeds and returns at least one account.
  </Step>
</Steps>

<Note>
  Managing a client's ad account rather than your own? Ask the client to add your X user to their ad account in X Ads Manager, then generate the access token pair as that user. The tokens carry whatever access that user has.
</Note>

***

## Selecting Your Connection

Custom app connections appear under the name you chose, with a **Custom app** badge on the Connections page. Select them in X Ads nodes, agents, and MCP exactly like any other X Ads connection.

***

## Rotating or Replacing the Tokens

Add the connection again with the **same connection name** and the new values. Markifact replaces the stored credentials in place, so workflows and agents bound to the connection keep working.

***

## Troubleshooting

<Accordion title="X rejected the credentials (401)">
  The four values do not belong together, or one was mistyped. The access token must have been generated under the same API key you pasted. Regenerate the access token pair on the app's **Keys and tokens** tab and paste all four again.
</Accordion>

<Accordion title="X refused access (403)">
  Either your developer account has no Ads API access yet, or the access token was generated while the app permissions were **Read only**. Fix the permissions under **User authentication settings**, regenerate the token pair (changing permissions does not update existing tokens), and try again.
</Accordion>

<Accordion title="These tokens cannot see any ad accounts">
  The X user behind the access token has no access to any ad account. Add them in X Ads Manager under account access, then regenerate the tokens.
</Accordion>

<Accordion title="X is rate limiting this token">
  The accounts endpoint allows 5 requests per 15 minutes per token, which the connection check uses once. Wait a few minutes and try again.
</Accordion>

***

## Summary

| Item                    | Where to Find                                 | What It Looks Like          |
| ----------------------- | --------------------------------------------- | --------------------------- |
| **API Key**             | Developer portal > your app > Keys and tokens | `Ab1cD2eF3gH4iJ5kL6mN7oP8q` |
| **API Key Secret**      | Same tab                                      | `r9S0tU1vW2xY3z...`         |
| **Access Token**        | Same tab, Access Token and Secret             | `1234567890-AbCdEf...`      |
| **Access Token Secret** | Generated with the access token               | `gH4iJ5kL6mN7oP8q...`       |

***

## Related

<CardGroup cols={2}>
  <Card title="White-label Connections" icon="tag" href="/core-concepts/white-label-connections">
    Overview of custom app connections across channels
  </Card>

  <Card title="Get Report" icon="chart-line" href="/nodes/x_ads/x_ads_get_report">
    Pull X Ads performance data
  </Card>
</CardGroup>