Skip to main content

​
Overview

Configure your own X (formerly Twitter) OAuth application to enable custom branding for the X authentication experience in Embedded Wallets. This guide walks you through creating an X Developer account, configuring an OAuth 2.0 app, and integrating with CDP. Time to complete: ~15-20 minutes
X (formerly known as Twitter) rebranded in 2023, but the authentication process is still commonly referred to as “Twitter login” or “X login”.

​
Prerequisites

Before you begin, ensure you have:
  • X Developer account: Free tier available at developer.x.com
  • CDP Project ID: Available in your CDP Portal dashboard
  • Access to CDP Portal: Permission to configure Embedded Wallets settings
Rate limits on free tier: X imposes strict rate limits even on the free developer tier. For production applications with significant traffic, you may need to upgrade to a paid tier.

​
Step 1: Create X Developer account

  1. Navigate to developer.x.com
  2. Click Sign In and authenticate with your X account
  3. If you don’t have developer access yet, click Apply for a developer account
  4. Complete the developer application:
    • What is your primary reason for using the X API?: Select the most appropriate option (e.g., “Building tools for X users”)
    • What are you planning to do with the X API?: Describe your application (e.g., “Enable users to authenticate and access web3 wallets using their X account”)
    • Will your app use Tweet, Retweet, Like, Follow, or Direct Message functionality?: Select “No” (unless you need these features)
    • Complete any additional required fields
  5. Review and accept the X Developer Agreement
  6. Click Submit and wait for approval (usually instant for basic access)
Most applications are approved instantly for basic OAuth access. If additional review is required, you’ll receive an email notification.

​
Step 2: Create X app

  1. Once your developer account is approved, navigate to the X Developer Portal
  2. Click + Create Project or + Add App
  3. Fill in the app details:
    • App name: Your application name (visible to users during OAuth, e.g., “My App”)
    • App description: Brief description of your application
    • Website URL: Your application’s website
    • Callback URL: Leave blank for now (we’ll configure this in Step 3)
  4. Click Create or Next
The app name you choose here will be displayed to users during the X OAuth flow, so use your official product name for brand consistency.

​
Step 3: Configure OAuth 2.0 settings

  1. In your X app dashboard, navigate to Settings or App settings
  2. Scroll to User authentication settings section
  3. Click Set up or Edit
  4. Configure OAuth 2.0:
    • App permissions: Select Read (minimum required for authentication)
    • Type of App: Select Web App
    • App info:
      • Callback URI / Redirect URL: Enter the exact URL: 
        https://api.cdp.coinbase.com/platform/v2/end-users/auth/oauth/x/callback
      • Website URL: Your application’s website URL
Critical: The Callback URI must match exactly as shown above. Any differences (including http vs https, trailing slashes, or typos) will cause authentication to fail.
  1. Click Save
  2. After saving, you’ll see your OAuth 2.0 credentials:
    • Client ID: Copy this value
    • Client Secret: Click Generate or Regenerate to create a secret, then copy it
Store your Client ID and Client Secret securely. You can always regenerate the Client Secret if needed, but this will invalidate the previous secret.

​
Step 4: Enable OAuth 2.0

Ensure OAuth 2.0 is properly enabled for your app:
  1. In your app settings, verify that OAuth 2.0 is enabled
  2. Confirm the Read permission is granted (minimum requirement)
  3. Check that the Callback URI is correctly configured
Additional app permissions (Write, Direct Messages) require X app review. For authentication purposes, Read permission is sufficient.

​
Step 5: Configure CDP Portal

Now that you have your X OAuth credentials, configure them in the CDP Portal:
  1. Navigate to the CDP Portal
  2. Select your project
  3. Go to Embedded Wallets > Authentication
  4. Find the X section
  5. Toggle Enable X OAuth to on
  6. Paste your Client ID from Step 3
  7. Paste your Client Secret from Step 3
  8. Click Save Changes
Your X OAuth configuration is now active. Any new authentication attempts will use your custom OAuth application instead of CDP’s default.

​
Step 6: Verification

Test your X OAuth configuration:
  1. In your application, ensure you’re calling the X sign-in method (see SDK Integration below)
  2. Click “Sign in with X”
  3. Verify that the OAuth consent screen shows your application name
  4. Complete the authentication flow
  5. Check that the user successfully signs in and their wallet is accessible
During testing, you can use any X account to authenticate. Unlike some providers, X doesn’t require adding test users during development.

​
SDK Integration

Integrate X authentication in your application using CDP’s SDK: 
import { useSignInWithOAuth } from '@coinbase/cdp-hooks';

function LoginButton() {
  const { signInWithOAuth } = useSignInWithOAuth();

  return (
    <button onClick={() => signInWithOAuth('x')} disabled={isLoading}>
      {isLoading ? 'Signing in...' : 'Sign in with X'}
    </button>
  );
}
The SDK automatically uses your custom X OAuth configuration when available. No code changes are needed when switching from CDP’s default to your custom OAuth application.

​
Production considerations

X imposes strict rate limits on OAuth and API requests:Free tier limits:
  • OAuth requests: Limited number of authentication requests per 15-minute window
  • User lookup: Limited API calls for fetching user information
  • Monthly caps: Overall monthly limits on API usage
For production:
  • Monitor usage: Track your OAuth request volume in X Developer Portal
  • Upgrade tiers: Consider X API Pro or Enterprise for higher limits
  • Rate limit handling: Implement proper error handling for rate limit responses (HTTP 429)
  • Caching: Cache user information to minimize API calls
Request rate limit increases:
  1. Navigate to X Developer Portal
  2. Go to your app settings
  3. Look for “Request rate limit increase” or contact X support
  4. Provide justification and expected usage patterns
Basic OAuth authentication only requires Read permission, which doesn’t require app review. However:
  • Additional permissions: Write, Direct Messages, or other advanced permissions require X app review
  • Review process: Can take several days to weeks
  • Elevated access: Some features require X API Pro or Enterprise subscription
For authentication purposes, Read permission is sufficient and doesn’t require review.
Ensure your X OAuth experience reflects your brand:
  • App name: Update to your official product name in app settings
  • App icon: Upload your logo in app settings (shown during OAuth flow)
  • App description: Keep concise and clear about what users are authenticating for
  • Website URL: Link to your main product page
Users will see this information every time they authenticate, so maintain professional branding.
  • Client Secret: Store securely (environment variables, secrets manager)
  • Rotation: Regenerate Client Secret periodically for security
  • Access control: Limit who can access your X Developer Portal account
  • Monitoring: Enable notifications for unusual app activity
  • Scopes: Only request minimum required permissions (Read for authentication)

​
Troubleshooting

Cause: The Callback URI in your X app configuration doesn’t match the redirect URL.Solution:
  1. In X Developer Portal, go to your app’s User authentication settings
  2. Verify the Callback URI exactly matches: https://api.cdp.coinbase.com/platform/v2/end-users/auth/oauth/x/callback
  3. Check for trailing slashes, http vs https, and typos
  4. Save changes in X Developer Portal (may take a few minutes to propagate)
  5. Try authentication again
Cause: The Client ID or Client Secret is incorrect or has been regenerated.Solution:
  1. Verify the Client ID in CDP Portal matches the one in X Developer Portal
  2. Verify the Client Secret in CDP Portal matches the current secret
  3. If you regenerated the Client Secret, update it in CDP Portal
  4. Ensure no extra spaces or characters were copied
  5. Check that the credentials are from the correct X app
Cause: Your app requires permissions that need X review, or the app hasn’t been approved.Solution:
  1. Verify you only selected Read permission (doesn’t require review)
  2. If you need additional permissions, submit your app for X review
  3. Check X Developer Portal for any pending review requirements
  4. Ensure your X Developer account is in good standing
  5. Contact X support if approval is taking longer than expected
Cause: You’ve exceeded X’s rate limits for OAuth requests.Solution:
  1. Implement exponential backoff retry logic in your application
  2. Cache user authentication states to reduce OAuth requests
  3. Monitor your usage in X Developer Portal
  4. Consider upgrading to X API Pro for higher limits
  5. Spread authentication requests over time if doing bulk testing
Cause: The user may have previously denied access, or there’s an issue with permissions.Solution:
  1. Ask the user to revoke app access in X settings and try again:
    • Go to X Settings > Security and account access > Apps and sessions
    • Find your app and revoke access
    • Try authenticating again
  2. Verify your app has the correct permissions (Read minimum)
  3. Check that the user’s X account is in good standing
  4. Ensure OAuth 2.0 is enabled in your app settings
Cause: This is likely an issue with your CDP configuration, not X OAuth.Solution:
  1. Check CDP status page for potential outages
  2. Verify your CDP Project ID is correct in your application
  3. Ensure you’re using the latest SDK version
  4. Check that the user’s X username/ID is being properly passed to CDP
  5. Contact CDP support if the issue persists

Custom Social Login Overview

Return to social login overview

Google OAuth Setup

Configure Google OAuth

Apple OAuth Setup

Configure Apple Sign In

Authentication Methods

Explore other authentication options