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

# Set up a Custom OAuth Provider

> Add any OAuth 2.0 provider — Spotify, Twitch, GitHub, or your own — as a Para login method, configured from the Developer Portal or the Para CLI.

Custom OAuth lets you add **any OAuth 2.0 provider** as a login method in Para — providers Para doesn't ship a built-in button for, like Spotify, Twitch, or GitHub, or an OAuth service of your own. Users sign in with that provider and get a Para embedded wallet, just like any other social login.

You register the provider as a **connection**: its OAuth endpoints, your client credentials, and a short **handle** that identifies it. The connection then appears in your login-method list, and the Para Modal renders it as a sign-in button with the label and logo you configure.

<Warning>
  **SDK version requirement.** Custom OAuth sign-in buttons only render in Para Modal / React SDK version **3.20.0** and later. Apps on older SDK versions are unaffected — Para simply doesn't send them your custom connections, so they keep showing your other login methods without errors. [Custom OIDC](/v3/general/developer-portal-custom-oidc) is different: a single OIDC provider works on current SDK versions too.
</Warning>

<Info>
  Custom OAuth is for **end users signing in through Para** with the provider. If your backend already authenticates users and you only need server-side wallets, see [Bring Your Own Auth](/v3/rest/byo-auth) instead.
</Info>

## How it works

1. A user taps your provider's button on the Para login screen.
2. Para redirects them to the provider's authorization page to sign in.
3. The provider redirects back to Para's callback with an authorization code.
4. Para exchanges the code at the provider's token endpoint, fetches the user's identity from the user-info endpoint, and creates or loads their Para wallet.

You give Para the provider's **authorization, token, and user-info URLs** plus a **client ID and secret** from an OAuth app you register with the provider; Para gives you a **redirect URI** to allowlist with them.

## Before you start

* A provider that supports the **OAuth 2.0 authorization-code flow** and exposes three endpoints: an authorization URL, a token URL, and a user-info URL that returns the signed-in user's id (as `id` or `sub`).
* Admin access to register an OAuth app with that provider, so you can obtain a client ID and secret.
* A Para project and API key — [create one](/v3/general/developer-portal-setup) if you haven't.

## 1. Register an app with the provider

In the provider's developer console, create an OAuth app and note its **Client ID** and **Client secret**.

Add Para's redirect URI to the app's allowed redirect / callback URIs:

<CodeGroup>
  ```text Production theme={null}
  https://api.getpara.com/internal/v1/auth/oauth/custom_oauth/callback
  ```

  ```text Beta (testing) theme={null}
  https://api.beta.getpara.com/internal/v1/auth/oauth/custom_oauth/callback
  ```
</CodeGroup>

<Note>
  Custom OAuth2 connections use only this one redirect URI (unlike Para's built-in social providers, which list two while older SDK versions are still in use). The exact URI for your environment is also shown in the connection dialog when you configure the provider in the next step.
</Note>

## 2. Add the connection in Para

Configure the connection from either the Developer Portal or the Para CLI — they write the same settings.

<Tabs>
  <Tab title="Developer Portal">
    <Steps>
      <Step title="Open the Authentication screen">
        In the [Developer Portal](https://developer.getpara.com), select your project and API key, then go to **Authentication** and choose **Add custom provider** under the login methods.
      </Step>

      <Step title="Choose Custom OAuth2 and name the connection">
        For **Provider**, select **Custom OAuth2 provider**, then set:

        * **Handle**: a short lowercase slug that identifies this connection, e.g. `spotify`. Up to 64 characters of `a-z 0-9 _ -`, starting with a letter or digit. Built-in provider names (like `google`) and `default` are reserved.
        * **Display name (internal)**: a label for your team (optional).
      </Step>

      <Step title="Enter the provider's endpoints and your client ID">
        * **Client ID** — from the app you registered in step 1.
        * **Authorization URL** — e.g. `https://accounts.spotify.com/authorize`.
        * **Token URL** — e.g. `https://accounts.spotify.com/api/token`.
        * **User info URL** — e.g. `https://api.spotify.com/v1/me`.
        * **Scopes** — space-separated scopes to request (whatever the provider needs to return the user's id).
      </Step>

      <Step title="Style the sign-in button">
        * **Sign-in button label** — e.g. "Continue with Spotify".
        * **Sign-in button logo URL** — an `https` URL for the button's logo in the login modal (optional).
      </Step>

      <Step title="Save, then add your client secret">
        Save the connection. Then use **Set secret** in the connection's menu to enter the **Client secret** from step 1. It's stored encrypted and never shown again.
      </Step>

      <Step title="Verify">
        Click **Verify** on the connection: Para runs a live reachability check against the provider's endpoints.
      </Step>

      <Step title="Enable and position the button">
        Turn the connection on in your login-method list. The order of the list is the order of the buttons in the Para Modal, so drag your new provider to where you want it.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Para CLI">
    Configure the same settings with the [Para CLI](/v3/cli/overview):

    ```bash theme={null}
    # Register the connection (or run `add` with no flags for interactive setup)
    para keys config oauth add \
      --provider CUSTOM_OAUTH \
      --handle spotify \
      --client-id your-client-id \
      --authorization-url https://accounts.spotify.com/authorize \
      --token-url https://accounts.spotify.com/api/token \
      --user-info-url https://api.spotify.com/v1/me \
      --scopes "user-read-email" \
      --button-label "Continue with Spotify"

    # Store the client secret (prompted; never echoed or written to .pararc)
    para keys config oauth set-secret spotify

    # Confirm Para can reach the provider
    para keys config oauth verify spotify

    # Enable it as a login method — handles sit alongside the built-in provider
    # names, and the list order is the button order in the Para Modal
    para keys config auth <key-id> --oauth-methods GOOGLE,spotify
    ```

    Review connections at any time:

    ```bash theme={null}
    para keys config oauth list
    para keys config oauth show spotify
    ```

    <Tip>
      `--oauth-methods` sets the full list, so include every provider you want enabled — built-in names and connection handles together, in the order you want the buttons to appear.
    </Tip>
  </Tab>
</Tabs>

## 3. Use it in your app

Once the connection is enabled — and your app is on a Para SDK version that supports custom connections — the Para Modal renders the sign-in button automatically with your configured label and logo. No extra SDK code is required.

Your custom connections are listed on the partner configuration your app already loads, under `authConfig.oauthConnections` (handle, provider, label, logo) — useful if you build your own login UI and want to render the same buttons.

## How users are identified

Users who sign in through a custom OAuth provider are identified by **the provider and their account id at that provider**. The same person signing in with the same provider account always resolves to the same Para user — including across different connections that point at the same provider.

<Note>
  The email address returned by a custom OAuth provider is not used to match existing Para accounts. A user who previously signed in with, say, Google will get a distinct Para account when they first sign in through your custom provider.
</Note>

## Troubleshooting

<AccordionGroup>
  <Accordion title="The provider button doesn't appear in the modal">
    Three things to check: the connection is **enabled**, its handle is present in your **login-method list**, and the app is running a Para SDK version that supports custom connections (see the version note at the top). Older SDK versions never receive custom connections — that's expected, not an error.
  </Accordion>

  <Accordion title="The redirect fails with a redirect_uri mismatch">
    The redirect URI registered with the provider must exactly match Para's callback for the environment you're using. Re-copy it from the connection dialog.
  </Accordion>

  <Accordion title="Registration is rejected with &#x22;needs manual review — contact Para support&#x22;">
    Para detected that this provider's sign-in domain is already associated with a different identity configuration. This is a safety check that prevents the same provider's users from being split across accounts. Contact support — resolution is quick once we've confirmed the provider setup.
  </Accordion>

  <Accordion title="Registration is rejected because of the user-info URL">
    The user-info URL must be a public `https` endpoint on a real domain — IP addresses, `localhost`, and single-label hosts are rejected. If the provider is one Para already supports natively (Google, Apple, Discord, Facebook, X/Twitter), register it as that provider with your own credentials instead of as a custom connection — the error message names the provider to pick.
  </Accordion>

  <Accordion title="Verify fails, or login errors at the token step">
    Confirm the three endpoint URLs are correct and publicly reachable over HTTPS, and that the client secret is set. Para authenticates to the token endpoint with your client ID and secret.
  </Accordion>
</AccordionGroup>

## Custom OAuth vs Custom OIDC

Both add your own provider as a Para login method — pick by what the provider supports:

| | Custom OAuth | [Custom OIDC](/v3/general/developer-portal-custom-oidc) |
| - | - | - |
| Provider type | Any OAuth 2.0 provider (authorize + token + user-info endpoints) | OpenID Connect providers (with a discovery document) |
| Typical use | Consumer platforms — Spotify, Twitch, GitHub, … | Enterprise SSO / your own IdP |
| SDK support | Para SDK **3.20.0** and later | Works on current SDK versions (single provider) |

## Next steps

<CardGroup cols={2}>
  <Card title="Custom OIDC" icon="key" href="/v3/general/developer-portal-custom-oidc">
    Add an OpenID Connect provider — enterprise SSO or your own IdP.
  </Card>

  <Card title="Configure Authentication" icon="fingerprint" href="/v3/react/guides/customization/developer-portal-authentication">
    The full Authentication screen — login methods, layout, and more.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.