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

# Twitter (X) Login

> Let your users sign in and register with their Twitter (X) accounts. Create an OAuth 2.0 app in the X Developer Portal and paste the credentials into Auth Settings — no code or .env edits required.

## Introduction

Adding **Sign in with Twitter (X)** lets your users register and log in with their X account. You'll create an app in the X Developer Portal using **OAuth 2.0**, then paste its credentials into your admin **Auth Settings** page. Credentials are stored securely in the database and applied automatically — there are no `.env` edits or code changes.

<Warning>
  **Twitter does not share email by default.** Email access requires the elevated **Request email address from users** permission on your X app, which is gated behind X's developer access tiers. If your app can't return an email, sign-in fails with "Your social account did not share an email address." Confirm email access is available on your X plan before relying on Twitter login.
</Warning>

## Before you start

* Admin access to your MagicAds platform.
* An X account with access to the [X Developer Portal](https://developer.x.com/).
* Your site's public URL (HTTPS strongly recommended).

## Step 1 — Note your Callback URL

The callback URL is where X sends users back after they approve sign-in:

```
https://YOUR_DOMAIN/auth/twitter/callback
```

For example: `https://app.example.com/auth/twitter/callback`

<Note>
  If your site uses a language prefix in its URLs (localization), the callback may include a locale segment such as `/en/auth/twitter/callback`. Whatever you enter in the **Callback URL** field in Auth Settings must match the value registered in your X app exactly.
</Note>

## Step 2 — Create an X (Twitter) app

<Steps>
  <Step title="Open the X Developer Portal">
    Go to [developer.x.com](https://developer.x.com/), sign in, and open **Developer Portal → Projects & Apps**. Create a Project and an App inside it if you don't have one.
  </Step>

  <Step title="Enable User authentication settings">
    Open your app and click **Set up** under **User authentication settings**.

    * **App permissions:** Read (sufficient for login). Enable **Request email address from users** if your access tier offers it.
    * **Type of App:** Web App / Automated App or Bot (a confidential client).
  </Step>

  <Step title="Set the Callback URI and website URL">
    * **Callback URI / Redirect URL:** add your callback from Step 1: `https://YOUR_DOMAIN/auth/twitter/callback`.
    * **Website URL:** `https://YOUR_DOMAIN`.

    Save the settings.
  </Step>

  <Step title="Copy the OAuth 2.0 credentials">
    After saving, X shows your **OAuth 2.0 Client ID** and **Client Secret**. Copy both.

    <Warning>
      Be sure to use the **OAuth 2.0** credentials — not the legacy API Key/Secret from the "Consumer Keys" section. Using the wrong pair causes a "Something went wrong" error on authorize.
    </Warning>
  </Step>
</Steps>

## Step 3 — Configure MagicAds

<Steps>
  <Step title="Open Auth Settings">
    In your platform, go to **Admin → Backend Settings → Auth Settings**.
  </Step>

  <Step title="Enable the master switch">
    Turn on **Social Media Login**. This is the master switch for all social providers, and it saves immediately.
  </Step>

  <Step title="Enable Twitter and enter credentials">
    Turn on the **Twitter** toggle, then fill in:

    * **API Key** → paste your X **OAuth 2.0 Client ID**.
    * **API Secret** → paste your X **OAuth 2.0 Client Secret**.
    * **Callback URL** → enter `https://YOUR_DOMAIN/auth/twitter/callback` (must match the Callback URI in the X app exactly).
  </Step>

  <Step title="Save">
    Click **Save**. Twitter only appears as a login option once it's enabled and both the API Key and API Secret are filled in.
  </Step>
</Steps>

### Field mapping reference

| MagicAds field | X (Twitter) value                                      |
| -------------- | ------------------------------------------------------ |
| API Key        | OAuth 2.0 Client ID                                    |
| API Secret     | OAuth 2.0 Client Secret                                |
| Callback URL   | Callback URI / Redirect URL (`/auth/twitter/callback`) |

## Step 4 — Test it

1. Open your site's **login page** in a private/incognito window.
2. Click **Sign in with Twitter**.
3. Authorize the app.
4. You should be redirected back and logged into your dashboard.

<Check>
  That's it — your users can now register and log in with Twitter (X).
</Check>

## Troubleshooting

| Symptom                                              | Likely cause                                                | Fix                                                                                                                  |
| ---------------------------------------------------- | ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- |
| "Your social account did not share an email address" | Email access not enabled on the X app/plan                  | Enable **Request email address from users** (requires the right X access tier). Without email, login can't complete. |
| Callback / redirect error                            | Callback URI mismatch                                       | Make the **Callback URI** in the X app exactly equal the **Callback URL** in Auth Settings.                          |
| "Something went wrong" on authorize                  | Used OAuth 1.0a Consumer Keys instead of OAuth 2.0          | Use the **OAuth 2.0 Client ID and Client Secret**, not the legacy API Key/Secret.                                    |
| Twitter button doesn't appear                        | Master switch off, Twitter toggle off, or credentials blank | Enable **Social Media Login** and **Twitter**, and fill both API Key and API Secret.                                 |
| "Registration is currently closed" after authorize   | New-user creation blocked                                   | Enable public registration in your platform settings, or pre-create the account.                                     |

<Note>
  The platform forces the modern OAuth 2.0 flow for Twitter automatically — you don't need to configure that. Credentials are stored securely and applied at runtime; no `.env` edits are needed.
</Note>