Set up a Custom OAuth Provider

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.

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 is different: a single OIDC provider works on current SDK versions too.

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 instead.

How it works

A user taps your provider’s button on the Para login screen.
Para redirects them to the provider’s authorization page to sign in.
The provider redirects back to Para’s callback with an authorization code.
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 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:

https://api.getpara.com/internal/v1/auth/oauth/custom_oauth/callback

https://api.beta.getpara.com/internal/v1/auth/oauth/custom_oauth/callback

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.

2. Add the connection in Para

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

Developer Portal
Para CLI

Open the Authentication screen

In the Developer Portal, select your project and API key, then go to Authentication and choose Add custom provider under the login methods.

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).

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).

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).

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.

Verify

Click Verify on the connection: Para runs a live reachability check against the provider’s endpoints.

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.

Configure the same settings with the Para CLI:

# 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:

para keys config oauth list
para keys config oauth show spotify

--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.

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.

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.

Troubleshooting

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.

Registration is rejected with "needs manual review — contact Para support"

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.

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.

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
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)

Getting Started

Choose a Path

Project Setup

Go Live

How Para Works

Shared Guides

Migrations

Set up a Custom OAuth Provider

How it works

Before you start

1. Register an app with the provider

2. Add the connection in Para

3. Use it in your app

How users are identified

Troubleshooting

Custom OAuth vs Custom OIDC

Next steps

Custom OIDC

Configure Authentication

​How it works

​Before you start

​1. Register an app with the provider

​2. Add the connection in Para

​3. Use it in your app

​How users are identified

​Troubleshooting

​Custom OAuth vs Custom OIDC

​Next steps

Custom OIDC

Configure Authentication

How it works

Before you start

1. Register an app with the provider

2. Add the connection in Para

3. Use it in your app

How users are identified

Troubleshooting

Custom OAuth vs Custom OIDC

Next steps