Custom Authentication

UTXOS supports three authentication modes, from zero-configuration default login to full integration with your existing authentication system. Choose the approach that matches your application needs.

What authentication modes are available?

Default Authentication

Default authentication requires no configuration. Enable providers from the dashboard and users authenticate through UTXOS-managed OAuth apps.

How It Works

1. User clicks “Sign in with Google” (or other provider)
2. User authenticates with the provider via UTXOS OAuth app
3. UTXOS creates or retrieves the user’s wallet
4. User is returned to your application

Enable Default Providers

1. Go to Dashboard > Project Settings > Authentication
2. Toggle on the providers you want to support
3. No additional configuration needed

Custom OAuth Credentials

Use your own OAuth credentials to customize the login experience. Your branding appears on the OAuth consent screen, and you control the requested permissions.

Benefits

• Your app name and logo on consent screens
• Control over OAuth scopes and permissions
• Consistent branding throughout the user journey
• Full control over OAuth app settings

Setup

Configuration

After creating your OAuth app with the provider:

1. Go to Dashboard > Project Settings > Authentication
2. Click Configure next to the provider
3. Enter your Client ID and Client Secret
4. Save changes

// SDK usage is the same - authentication method is configured in dashboard
import { Web3Sdk } from "@utxos/sdk";
 
const sdk = new Web3Sdk({
  projectId: process.env.NEXT_PUBLIC_UTXOS_PROJECT_ID,
});
 
// Users see your custom OAuth app branding
const wallet = await sdk.wallet.connect();

Third-Party Authentication

For applications with existing OAuth2 authentication, pass your users’ refresh tokens to UTXOS. This skips the UTXOS login prompt entirely, since users already authenticated with your system.

Benefits

• No duplicate login prompts
• Seamless integration with existing auth
• Single sign-on experience
• Users stay in your authentication flow

How It Works

1. User authenticates with your application (your existing flow)
2. You obtain a refresh token from the OAuth provider
3. Pass the refresh token to UTXOS SDK
4. UTXOS uses the token to verify identity and create/retrieve the wallet

Implementation

import { Web3Sdk } from "@utxos/sdk";
 
const sdk = new Web3Sdk({
  projectId: process.env.NEXT_PUBLIC_UTXOS_PROJECT_ID,
});
 
// User already authenticated with your system
// You have their OAuth refresh token
const userRefreshToken = await getRefreshTokenFromYourAuthSystem();
 
// Pass the token to UTXOS
const wallet = await sdk.wallet.connectWithToken({
  provider: "google", // or "discord", "twitter", "apple"
  refreshToken: userRefreshToken,
});
 
// Wallet is now available without additional login
const address = await wallet.cardano.getChangeAddress();

Requirements

Supported Providers

Security Considerations

• Refresh tokens are sensitive. Transmit them only over HTTPS.
• Tokens should be passed server-side when possible.
• Implement proper token storage and rotation in your authentication system.

Provider Setup Guides

For detailed setup instructions for each provider:

Next Steps

• Authentication Provider Overview - Full authentication documentation
• Custom Branding - Customize wallet appearance
• Wallet Integration - Integrate wallets into your app