Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.phantom.com/llms.txt

Use this file to discover all available pages before exploring further.

To use Phantom Connect in development and production, you must configure allowed origins and redirect URLs in Phantom Portal. These settings tell Phantom where your app is allowed to run and where users can be redirected after authentication. Both are required to connect users.

​
Allowed origins

Allowed origins define where your app is allowed to initiate a connection from. Phantom will only connect if the request comes from one of these domains. This prevents other websites from impersonating your app.

​
Add allowed origins

  1. In Phantom Portal, expand your app in the left navigation and select Set Up.
  2. Scroll to Allowed Origins.
  3. Enter a domain where your app runs.
  4. Select Add.

​
Allowed origin requirements

  • Include the protocol (https:// for production).
  • Use exact domains only.
  • Do not include paths, query strings, or wildcards.

​
Examples

EnvironmentExample
Productionhttps://your-app.com
Staginghttps://staging.your-app.com
Local developmenthttp://your-local-url:PORT
If your app runs in multiple environments, add each origin separately.

​
Redirect URLs

Redirect URLs define where users are sent after authentication. These are required for social login flows (Google, Apple) and for completing the Phantom Connect handshake. Redirect URLs can be web URLs or mobile app URIs.

​
Add redirect URLs

  1. In Phantom Portal, expand your app in the left navigation and select Set Up.
  2. Scroll to Redirect URLs.
  3. Enter a valid redirect URL.
  4. Select Add.

​
Redirect URL requirements

  • Must exactly match the URL used in your app.
  • Must be added and allowlisted in Phantom Portal before you can use it in production.
  • Multiple redirect URLs are allowed.

​
Examples

The redirect URL can be any page in your app. It does not need to be a dedicated callback path. The SDK handles the OAuth handshake automatically wherever PhantomProvider is mounted.
Use caseExample
Web apphttps://your-app.com/
Local developmenthttp://your-local-url:PORT/
Mobile appyour-app-scheme://
When using Google or Apple login, users are redirected to one of these URLs after authentication. If the redirect URL is missing or mismatched, login will fail.

​
Common setup mistakes

  • Adding a redirect URL but forgetting to add the corresponding allowed origin.
  • Including paths or wildcards in allowed origins.
  • Using a redirect URL in code that hasn’t been added to Phantom Portal.
  • Using http:// for production domains.

​
Troubleshooting

​
Auth2 /login/start request failed (400). Bad Request

This error means Phantom’s auth server rejected the login attempt before it started. It is always caused by a mismatch between your app’s configuration and what is registered in Phantom Portal. Check the following in order: 1. Is your app’s origin in Allowed Origins? The origin is the protocol + host + port (if non-default) where your app is running, with no path and no trailing slash.
App URLCorrect origin to add
http://your-local-url:PORT/http://your-local-url:PORT
https://your-app.com/dashboardhttps://your-app.com
2. Does your redirectUrl in code exactly match an entry in Phantom Portal? Every character must match, including trailing slashes. Find where your SDK sets redirectUrl and compare it against your Phantom Portal entries: 
import type { ReactNode } from "react";
import { PhantomProvider, AddressType } from "@phantom/react-sdk";

export function AppProviders({ children }: { children: ReactNode }) {
  return (
    <PhantomProvider
      config={{
        providers: ["google", "apple", "injected"],
        appId: "your-app-id",
        addressTypes: [AddressType.solana],
        authOptions: {
          // Must match exactly what you registered in Phantom Portal
          // Production:        https://your-app.com/
          // Local development: http://your-local-url:PORT/
          redirectUrl: "https://your-app.com/",
        },
      }}
    >
      {children}
    </PhantomProvider>
  );
}
3. Does your redirectUrl point to a URL your running app will actually receive? A common mistake is setting a redirect URL for one environment while running the app in a different one. A typical example is a local port mismatch: if redirectUrl is http://your-local-url:PORT but the dev server is running on a different port, the auth code is delivered to the wrong address and login fails. Check that the scheme, host, and port in redirectUrl all match where your app is currently running. 4. Are you testing in a different environment than you registered? Each environment is a separate origin. Add each one individually in Phantom Portal if you use more than one.

​
Need help?

Contact Phantom developer support.

​
Next steps

Verify your domain

Previous: Verify your domain

Edit app info

Next: Add your app information