Skip to main content

Privy Authentication API

Integrate Web3 authentication via Privy for seamless user onboarding with email, social logins, and crypto wallets. Supports account linking, multi-method authentication, and wallet address management.

Login with Privy​

POST/api/privy/auth/login

Login with Privy Token

Authenticate user using Privy access token. Supports new user registration and existing user login. Token can be provided in request body or Authorization header. Creates BRDZ session and maps Privy identity to internal user system.

Parameters

privy_tokenstringrequired

Privy access token from frontend authentication (can also be provided in Authorization header)

Request Body

{
  "privy_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}

Response

200Authentication successful
{
  "success": true,
  "message": "User logged in successfully",
  "data": {
    "user": {
      "user_id": 123,
      "username": "john_doe",
      "email": "john@example.com",
      "role": "user",
      "user_status": "active",
      "created": "2024-01-15T10:30:00Z"
    },
    "auth": {
      "method": "email",
      "privy_user_id": "did:privy:123456789",
      "verified_at": "2024-01-15T10:30:00Z",
      "is_new_user": false
    },
    "session": {
      "user_id": 123,
      "username": "john_doe",
      "email": "john@example.com",
      "role": "user",
      "auth_method": "email",
      "privy_user_id": "did:privy:123456789",
      "verified_at": "2024-01-15T10:30:00Z"
    }
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
400Missing or invalid token
{
  "success": false,
  "error": {
    "code": "MISSING_TOKEN",
    "message": "Privy access token is required in body or Authorization header"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
401Authentication failed
{
  "success": false,
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Failed to authenticate with Privy"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
200_new_userNew user registered and logged in
{
  "success": true,
  "message": "New user registered and logged in",
  "data": {
    "user": {
      "user_id": 124,
      "username": "jane_doe",
      "email": "jane@example.com",
      "role": "user",
      "user_status": "active",
      "created": "2024-01-15T10:30:00Z"
    },
    "auth": {
      "method": "google",
      "privy_user_id": "did:privy:987654321",
      "verified_at": "2024-01-15T10:30:00Z",
      "is_new_user": true
    }
  }
}
curl -X POST https://api.brdz.link/api/privy/auth/login \
-H "Content-Type: application/json" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "privy_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}'
POST/api/privy/auth/link

Link Privy Account to Existing User

Connect Privy authentication method to existing BRDZ user account. Allows users to add additional authentication methods (email, social, wallet) to their existing account. Requires existing BRDZ authentication.

Parameters

privy_tokenstringrequired

Privy access token for the authentication method to link

user_idnumber

User ID (can be provided via authenticated session or request body)

Request Body

{
  "privy_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "user_id": 123
}

Response

200Account linked successfully
{
  "success": true,
  "message": "Privy account linked successfully",
  "data": {
    "user": {
      "user_id": 123,
      "username": "john_doe",
      "email": "john@example.com",
      "user_status": "active"
    },
    "privy_mapping": {
      "id": 456,
      "privy_user_id": "did:privy:987654321",
      "auth_provider": "google",
      "wallet_address": null,
      "is_primary": false,
      "created_at": "2024-01-15T10:30:00Z"
    }
  },
  "message_detail": "Google authentication has been linked to your BRDZ account",
  "timestamp": "2024-01-15T10:30:00Z"
}
400Missing required fields
{
  "success": false,
  "error": {
    "code": "MISSING_USER_ID",
    "message": "User ID is required - please authenticate with BRDZ first"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
409Mapping already exists
{
  "success": false,
  "error": {
    "code": "MAPPING_EXISTS",
    "message": "This Privy account is already linked to a BRDZ user"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
curl -X POST https://api.brdz.link/api/privy/auth/link \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_BRDZ_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "privy_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
}'

Get Privy Profile​

GET/api/privy/auth/profile

Get User's Privy Profile

Retrieve all connected Privy authentication methods for current user. Shows primary authentication method, connected accounts, and security status. Users can only access their own profile unless admin.

Response

200Profile retrieved successfully
{
  "success": true,
  "message": "Privy profile retrieved successfully",
  "data": {
    "user_id": 123,
    "total_connected_accounts": 3,
    "connected_accounts": [
      {
        "id": 456,
        "provider": "Email",
        "auth_provider": "email",
        "wallet_address": null,
        "is_primary": true,
        "connected_at": "2024-01-10T10:30:00Z",
        "last_used": "2024-01-15T09:15:00Z",
        "status": "primary"
      },
      {
        "id": 457,
        "provider": "Google",
        "auth_provider": "google",
        "wallet_address": null,
        "is_primary": false,
        "connected_at": "2024-01-12T14:20:00Z",
        "last_used": "2024-01-14T16:45:00Z",
        "status": "secondary"
      },
      {
        "id": 458,
        "provider": "Crypto Wallet",
        "auth_provider": "wallet",
        "wallet_address": "0x1234567890123456789012345678901234567890",
        "is_primary": false,
        "connected_at": "2024-01-13T11:30:00Z",
        "last_used": "2024-01-15T08:00:00Z",
        "status": "secondary"
      }
    ],
    "primary_auth": {
      "provider": "Email",
      "connected_at": "2024-01-10T10:30:00Z"
    }
  },
  "security_info": {
    "has_multiple_methods": true,
    "can_remove_accounts": true
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
400Missing user ID
{
  "success": false,
  "error": {
    "code": "MISSING_USER_ID",
    "message": "User ID is required"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
403Access denied
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You can only access your own Privy profile"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
curl -X GET https://api.brdz.link/api/privy/auth/profile \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"

Get Specific User's Privy Profile​

GET/api/privy/auth/profile/{user_id}

Get Specific User's Privy Profile

Retrieve Privy authentication methods for specific user. Admin access required to view other users' profiles. Same response format as general profile endpoint.

Parameters

user_idstringrequired

User ID to get profile for (path parameter)

Response

200Profile retrieved successfully
{
  "success": true,
  "message": "Privy profile retrieved successfully",
  "data": {
    "user_id": 124,
    "total_connected_accounts": 2,
    "connected_accounts": [
      {
        "id": 459,
        "provider": "Google",
        "auth_provider": "google",
        "wallet_address": null,
        "is_primary": true,
        "connected_at": "2024-01-11T15:45:00Z",
        "last_used": "2024-01-15T10:20:00Z",
        "status": "primary"
      },
      {
        "id": 460,
        "provider": "Crypto Wallet",
        "auth_provider": "wallet",
        "wallet_address": "0x9876543210987654321098765432109876543210",
        "is_primary": false,
        "connected_at": "2024-01-14T09:30:00Z",
        "last_used": "2024-01-15T07:45:00Z",
        "status": "secondary"
      }
    ],
    "primary_auth": {
      "provider": "Google",
      "connected_at": "2024-01-11T15:45:00Z"
    }
  },
  "security_info": {
    "has_multiple_methods": true,
    "can_remove_accounts": true
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
403Admin access required
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You can only access your own Privy profile"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
curl -X GET https://api.brdz.link/api/privy/auth/profile/124 \
-H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"
POST/api/privy/auth/link-wallet

Connect Wallet Address via Privy

Connect additional crypto wallet address to user account through Privy. Verifies Privy token contains wallet information and creates mapping for Web3 authentication and transactions.

Parameters

privy_tokenstringrequired

Privy access token containing wallet information

wallet_addressstring

Specific wallet address to link (uses first wallet from token if not provided)

user_idnumber

User ID (typically provided via authenticated session)

Request Body

{
  "privy_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "wallet_address": "0x1234567890123456789012345678901234567890"
}

Response

200Wallet linked successfully
{
  "success": true,
  "message": "Wallet address linked successfully",
  "data": {
    "user_id": 123,
    "wallet_address": "0x1234567890123456789012345678901234567890",
    "privy_user_id": "did:privy:wallet123456",
    "auth_provider": "wallet",
    "linked_at": "2024-01-15T10:30:00Z"
  },
  "instructions": [
    "This wallet is now connected to your BRDZ account",
    "You can use it for Web3 authentication",
    "The wallet can be used for crypto transactions"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}
400Missing wallet information
{
  "success": false,
  "error": {
    "code": "NO_WALLET_IN_TOKEN",
    "message": "Privy token does not contain wallet information"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
409Wallet already linked
{
  "success": false,
  "error": {
    "code": "WALLET_ALREADY_LINKED",
    "message": "This wallet address is already linked to an account"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
curl -X POST https://api.brdz.link/api/privy/auth/link-wallet \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "privy_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "wallet_address": "0x1234567890123456789012345678901234567890"
}'

Disconnect Privy Authentication​

DELETE/api/privy/auth/disconnect

Remove Privy Authentication Method

Disconnect specific Privy authentication method from user account. Requires explicit confirmation for security. Cannot remove primary authentication method if it's the only one connected.

Parameters

privy_user_idstringrequired

Privy user ID of the authentication method to remove

confirmationstringrequired

Must be exactly 'disconnect' for security confirmation

user_idnumber

User ID (typically provided via authenticated session)

Request Body

{
  "privy_user_id": "did:privy:987654321",
  "confirmation": "disconnect"
}

Response

200Authentication method disconnected
{
  "success": true,
  "message": "Privy authentication disconnected successfully",
  "data": {
    "user_id": 123,
    "disconnected_provider": "google",
    "privy_user_id": "did:privy:987654321",
    "disconnected_at": "2024-01-15T10:30:00Z"
  },
  "security_notice": "You can reconnect this authentication method at any time",
  "timestamp": "2024-01-15T10:30:00Z"
}
400Confirmation required
{
  "success": false,
  "error": {
    "code": "CONFIRMATION_REQUIRED",
    "message": "Please provide confirmation: \"disconnect\" to proceed"
  },
  "instruction": "This action will remove the authentication method from your account",
  "timestamp": "2024-01-15T10:30:00Z"
}
404Authentication method not found
{
  "success": false,
  "error": {
    "code": "AUTH_NOT_FOUND",
    "message": "Authentication method not found or not owned by user"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
409Cannot disconnect primary method
{
  "success": false,
  "error": {
    "code": "CANNOT_DISCONNECT_PRIMARY",
    "message": "Cannot disconnect the only authentication method"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
curl -X DELETE https://api.brdz.link/api/privy/auth/disconnect \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY" \
-d '{
  "privy_user_id": "did:privy:987654321",
  "confirmation": "disconnect"
}'

Get Health Status​

GET/api/privy/health

Check Privy Service Health

Get comprehensive health status for Privy authentication service. Checks configuration completeness, service availability, and endpoint status. Returns operational status or degraded status if configuration issues detected.

Response

200Health status retrieved - operational
{
  "success": true,
  "message": "Privy service health check completed",
  "data": {
    "service": "Privy Authentication Service",
    "status": "operational",
    "version": "1.0.0",
    "environment": "production",
    "configuration": {
      "app_id": "configured",
      "app_secret": "configured",
      "verification_key": "configured",
      "database_connection": "active"
    },
    "endpoints": [
      "POST /privy/auth/login",
      "POST /privy/auth/link",
      "GET /privy/auth/profile",
      "POST /privy/auth/link-wallet",
      "DELETE /privy/auth/disconnect"
    ],
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
500Health check failed
{
  "success": false,
  "error": {
    "code": "HEALTH_CHECK_FAILED",
    "message": "Privy service health check failed",
    "details": "Database connection error"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
200_degradedHealth status retrieved - degraded (configuration issues)
{
  "success": true,
  "message": "Privy service health check completed",
  "data": {
    "service": "Privy Authentication Service",
    "status": "degraded",
    "version": "1.0.0",
    "environment": "development",
    "configuration": {
      "app_id": "missing",
      "app_secret": "configured",
      "verification_key": "configured",
      "database_connection": "active"
    },
    "endpoints": [
      "POST /privy/auth/login",
      "POST /privy/auth/link",
      "GET /privy/auth/profile",
      "POST /privy/auth/link-wallet",
      "DELETE /privy/auth/disconnect"
    ],
    "issues": [
      "PRIVY_APP_ID not configured"
    ],
    "timestamp": "2024-01-15T10:30:00Z"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
curl -X GET https://api.brdz.link/api/privy/health \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"

Get Usage Statistics​

GET/api/privy/stats

Get Privy Usage Statistics

Retrieve comprehensive usage statistics from privy_users table including authentication method breakdown, user activity metrics, and recent signup trends. Provides insights into authentication patterns and service adoption.

Response

200Statistics retrieved successfully
{
  "success": true,
  "message": "Privy usage statistics retrieved",
  "data": {
    "overview": {
      "total_privy_accounts": 1487,
      "unique_brdz_users": 1250,
      "primary_auth_methods": 1250,
      "accounts_per_user_avg": 1.19
    },
    "auth_methods": {
      "email": 567,
      "google": 324,
      "wallet": 189,
      "twitter": 98,
      "discord": 72
    },
    "activity": {
      "active_last_24h": 156,
      "active_last_7d": 723,
      "new_accounts_30d": 234
    },
    "recent_signups": [
      {
        "date": "2024-01-15",
        "new_accounts": 12
      },
      {
        "date": "2024-01-14",
        "new_accounts": 18
      },
      {
        "date": "2024-01-13",
        "new_accounts": 15
      },
      {
        "date": "2024-01-12",
        "new_accounts": 9
      },
      {
        "date": "2024-01-11",
        "new_accounts": 21
      },
      {
        "date": "2024-01-10",
        "new_accounts": 14
      },
      {
        "date": "2024-01-09",
        "new_accounts": 16
      }
    ]
  },
  "generated_at": "2024-01-15T10:30:00Z"
}
500Statistics retrieval failed
{
  "success": false,
  "error": {
    "code": "STATS_ERROR",
    "message": "Failed to retrieve Privy statistics",
    "details": "Database query failed"
  },
  "timestamp": "2024-01-15T10:30:00Z"
}
curl -X GET https://api.brdz.link/api/privy/stats \
-H "Authorization: Bearer YOUR_ADMIN_JWT_TOKEN" \
-H "x-api-key: YOUR_API_KEY"

Integration Workflows​

Complete Privy Authentication Flow​

  1. New User Registration:

    // Frontend: User completes Privy authentication
    const privyToken = await privyAuth.authenticate();

    // Backend: Login/register with Privy token
    const result = await loginWithPrivy({ privy_token: privyToken });

    if (result.data.auth.is_new_user) {
      console.log('New user registered:', result.data.user);
    }

  2. Link Additional Authentication Methods:

    // User already has BRDZ account, wants to add Google login
    const googleToken = await privyAuth.linkGoogle();

    const linkResult = await linkPrivyAccount({ 
      privy_token: googleToken 
    });

    console.log('Google linked:', linkResult.data.privy_mapping.auth_provider);

  3. Connect Crypto Wallet:

    // User wants to add wallet for Web3 features
    const walletToken = await privyAuth.connectWallet();

    const walletResult = await linkWalletAddress({
      privy_token: walletToken,
      wallet_address: '0x1234...'
    });

  4. Profile Management:

    // Check connected methods
    const profile = await getPrivyProfile();

    // Remove unwanted authentication method
    await disconnectPrivyAuth({
      privy_user_id: 'did:privy:unwanted123',
      confirmation: 'disconnect'
    });

Database Integration​

Based on controller implementation:

  • User Registration: Creates new BRDZ user when Privy token is for unregistered user
  • Account Mapping: Links Privy identity to existing BRDZ user via mapping table
  • Authentication Tracking: Logs authentication methods and usage patterns
  • Security Management: Prevents disconnection of primary/only authentication method

Authentication Methods Supported​

Via Privy integration:

  • Email/Password: Traditional email authentication
  • Social Logins: Google, Twitter, Discord integration
  • Crypto Wallets: MetaMask, WalletConnect, and other Web3 wallets
  • Multi-Method: Users can connect multiple authentication methods
  • Primary/Secondary: One method designated as primary for account recovery

Security Features​

  • Token Validation: Verifies Privy tokens before creating sessions
  • Access Control: Users can only manage their own authentication methods
  • Confirmation Required: Explicit confirmation needed for disconnection
  • Admin Oversight: Administrators can view user authentication profiles
  • Audit Trail: Logs all authentication events and changes
Authentication Requirements

Most endpoints require BRDZ JWT token + API key. The login endpoint is public but requires valid Privy token. Profile access is restricted to account owners and admins.

Privy Integration

This API works with Privy's frontend SDK. Obtain Privy tokens client-side, then exchange for BRDZ sessions server-side. Supports seamless Web2/Web3 authentication flows.

Multi-Method Authentication

Users can connect multiple authentication methods for flexibility and security. Always maintain at least one active method. Primary method is used for account recovery.