Authentication

This document explains how authentication works with the Sivi UI SDK and provides examples for both general and enterprise implementations.

Authentication Methods Overview

Sivi UI SDK supports two authentication approaches:

1. General UI SDK Authentication - Default authentication flow with user login UI
2. Enterprise Authentication - Frictionless machine-to-machine authentication without end-user intervention

1. General UI SDK Authentication

For standard implementations, the authentication process follows these steps:

1. When your application first loads the Sivi widget, it displays a "Get Started" button
2. When users click this button, they are redirected to instant.sivi.ai in a new tab
3. Users complete the login/signup process
4. Upon successful authentication, the widget receives access and refresh tokens
5. The authentication state is maintained across sessions via browser storage by the widget

General Example

// Basic implementation - no custom authentication code required
window.SIVI.show({
    type: "socialMedia",
    subtype: "instagram",
    // Other configuration options...
}, "sivi-container");

In this scenario, the user will see the login button and complete the standard authentication flow.

2. Enterprise Authentication

Enterprise implementations benefit from a frictionless authentication system with these advantages:

• User Abstraction - Sivi does not store any of your users' personal information
• Seamless Integration - Users don't need to create separate Sivi accounts
• Programmatic Auth - Authentication happens via API without user intervention

The authentication process works as follows:

1. Your frontend application captures the WIDGET_NEED_LOGIN event from the Sivi widget
2. Your backend server makes a call to the Sivi Login User API to obtain tokens for your user
3. Your application provides the tokens to the widget during initialization
4. The widget uses these tokens for all subsequent API calls to Sivi Server

Enterprise Authentication Sequence Flow

Enterprise Authentication API

To authenticate users programmatically, use the Login User API endpoint:

See the Login User API Reference for complete details.

Widget Authentication Example

Implementing enterprise authentication with the widget using the WIDGET_INIT event:

// First register the event handler to provide auth tokens
window.SIVI.events(async (event, responseCallback) => {
  switch (event.type) {
    case 'WIDGET_NEED_LOGIN': {
      try {
        // Get tokens from your backend server
        const authResponse = await fetch('/your-backend-auth-endpoint', {
          method: 'POST',
          headers: {
            'Content-Type': 'application/json',
          },
          body: JSON.stringify({
            userId: 'your-current-user-id' // this will be passed as an abstract user id for us.
          })
        });
        
        const authData = await authResponse.json();
        
        // Return tokens to the widget
        responseCallback({
          accessToken: authData.accessToken,
          refreshToken: authData.refreshToken
        });
      } catch (error) {
        console.error('Authentication failed', error);
        responseCallback({
          error: 'Authentication failed'
        });
      }
      break;
    }
    
    // Handle other events...
    default:
      responseCallback('done');
      break;
  }
});

// Then open the widget
window.SIVI.show({
  type: "socialMedia",
  subtype: "instagram",
  // Other configuration options...
}, "sivi-container");

Token Refresh Handling

Widget handles the token refresh automatically after setting the tokens.

Security Best Practices

1. Never expose your Enterprise API Key in client-side code
2. Always authenticate users on your backend server
3. Use HTTPS for all API calls
4. Validate user identity before requesting tokens

For more details on enterprise features, see the Enterprise Features documentation.