Class MosaiaAuth

Authentication API client for the Mosaia SDK

This class provides comprehensive authentication functionality for the Mosaia SDK, supporting multiple authentication flows:

  • Password-based authentication
  • Client credentials authentication
  • Token refresh operations
  • OAuth token management
  • Session handling

The class integrates with ConfigurationManager for centralized configuration management and uses APIClient for making authenticated HTTP requests.

Remarks

All authentication methods return a MosaiaConfig object that can be used to configure the main SDK client. The configuration includes access tokens, refresh tokens, and session information.

Example

Basic usage with password authentication:

const auth = new MosaiaAuth();

try {
  // Sign in with email/password
  const config = await auth.signInWithPassword(
    'user@example.com',
    'password'
  );
  
  // Use the config with the SDK
  const mosaia = new MosaiaClient(config);
} catch (error) {
  console.error('Authentication failed:', error.message);
}

Example

Client credentials authentication:

const auth = new MosaiaAuth();

try {
  // Sign in with client credentials
  const config = await auth.signInWithClient(
    'client-id',
    'client-secret'
  );
  
  // Use the config with the SDK
  const mosaia = new MosaiaClient(config);
} catch (error) {
  console.error('Client auth failed:', error.message);
}

Example

Token refresh and sign out:

// Refresh token when needed
const newConfig = await auth.refreshToken();
mosaia.config = newConfig;

// Sign out when done
await auth.signOut();

Constructors

constructor

Methods

signInWithPassword signInWithClient refreshToken refreshOAuthToken signOut refresh

Constructors

constructor

  • new MosaiaAuth(config?: MosaiaConfig): MosaiaAuth

    Creates a new Authentication API client instance

    Initializes the authentication client with an optional configuration. If no configuration is provided, it uses the ConfigurationManager to get the current configuration.

    Parameters

    • Optionalconfig: MosaiaConfig

      Optional configuration object

      Configuration interface for the Mosaia SDK

      This interface defines all configuration options available when initializing the Mosaia SDK client. It includes authentication settings, API endpoints, and optional context parameters.

      • OptionalapiKey?: string

        API key for authentication (optional if using OAuth)

      • Optionalversion?: string

        API version to use (defaults to '1')

      • OptionalapiURL?: string

        Base URL for API requests (defaults to https://api.mosaia.ai)

      • OptionalclientId?: string

        Client ID for client credentials flows (Optional)

      • OptionalclientSecret?: string

        Client secret for client credentials flow (optional)

      • Optionalverbose?: boolean

        Enable verbose HTTP request/response logging (defaults to false)

      • Optionalsession?: SessionCredentials

        Session credentials for OAuth and token-based authentication (optional)

    Returns MosaiaAuth

    Example

    // Create with default configuration
    const auth = new MosaiaAuth();

    // Create with custom configuration
    const auth = new MosaiaAuth({
      apiURL: 'https://api.mosaia.ai',
      clientId: 'your-client-id'
    });

    Throws

    When required configuration values are missing

Methods

signInWithPassword

  • signInWithPassword(email: string, password: string): Promise<MosaiaConfig>

    Sign in using email and password authentication

    Authenticates a user with their email and password credentials. Returns a configured Mosaia client instance with the obtained access token.

    Parameters

    • email: string

      The user's email address

    • password: string

      The user's password

    Returns Promise<MosaiaConfig>

    Promise that resolves to a configured Mosaia client instance

    Remarks

    The clientId is automatically retrieved from the configuration. Ensure the configuration has a clientId set before calling this method.

    Throws

    When authentication fails or network errors occur

    Throws

    When clientId is not found in configuration

    Example

    const auth = new MosaiaAuth();
    try {
      const mosaiaConfig = await auth.signInWithPassword('user@example.com', 'password', 'client-id');
      mosaia.config = mosaiaConfig;
      console.log('Successfully authenticated');
    } catch (error) {
      console.error('Authentication failed:', error.message);
    }

signInWithClient

  • signInWithClient(clientId: string, clientSecret: string): Promise<MosaiaConfig>

    Sign in using client credentials authentication

    Authenticates an application using client ID and client secret. This flow is typically used for server-to-server authentication where no user interaction is required.

    Parameters

    • clientId: string

      The OAuth client ID

    • clientSecret: string

      The OAuth client secret

    Returns Promise<MosaiaConfig>

    Promise that resolves to a configured Mosaia client instance

    Throws

    When authentication fails or network errors occur

    Example

    const auth = new MosaiaAuth();
    try {
      const mosaiaConfig = await auth.signInWithClient('client-id', 'client-secret');
      mosaia.config = mosaiaConfig;
      console.log('Successfully authenticated with client credentials');
    } catch (error) {
      console.error('Client authentication failed:', error.message);
    }

refreshToken

  • refreshToken(token?: string): Promise<MosaiaConfig>

    Refresh an access token using a refresh token

    Obtains a new access token using an existing refresh token. This method can be used to extend a user's session without requiring them to re-enter their credentials.

    Parameters

    • Optionaltoken: string

      Optional refresh token. If not provided, attempts to use the refresh token from the current configuration

    Returns Promise<MosaiaConfig>

    Promise that resolves to an updated MosaiaConfig

    Throws

    When refresh token is missing or refresh fails

    Example

    const auth = new MosaiaAuth();
    try {
      // Use refresh token from config
      const mosaia = await auth.refreshToken();
      
      // Or provide a specific refresh token
      const mosaiaConfig = await auth.refreshToken('specific-refresh-token');
      mosaia.config = mosaiaConfig;
    } catch (error) {
      console.error('Token refresh failed:', error.message);
    }

refreshOAuthToken

  • refreshOAuthToken(refreshToken: string): Promise<MosaiaConfig>

    Refreshes an OAuth access token using a refresh token

    This method exchanges a refresh token for a new access token when the current access token expires. This allows for long-term authentication without requiring user re-authentication.

    Parameters

    • refreshToken: string

      The refresh token received from the initial token exchange

    Returns Promise<MosaiaConfig>

    Promise that resolves to a new OAuth token response

    Throws

    When the refresh fails (invalid refresh token, expired, etc.)

    Example

    // When access token expires, use refresh token to get new tokens
    try {
      const mosaiaConfig = await oauth.refreshToken(refreshToken);
      mosaia.config = mosaiaConfig;
      console.log('New access token:', mosaiaConfig.apiKey);
      console.log('New refresh token:', mosaiaConfig.refreshToken);
    } catch (error) {
      // Refresh token expired, user needs to re-authenticate
      console.error('Token refresh failed:', error);
    }

signOut

  • signOut(apiKey?: string): Promise<void>

    Sign out and invalidate the current session

    Invalidates the current access token and clears the configuration. This method should be called when a user logs out or when you want to ensure the current session is terminated.

    Parameters

    • OptionalapiKey: string

      Optional API key to sign out. If not provided, uses the API key from the current configuration

    Returns Promise<void>

    Promise that resolves when sign out is complete

    Throws

    When API key is missing or sign out fails

    Example

    const auth = new MosaiaAuth();
    try {
      // Sign out using API key from config
      await auth.signOut();
      
      // Or provide a specific API key
      await auth.signOut('specific-api-key');
      console.log('Successfully signed out');
    } catch (error) {
      console.error('Sign out failed:', error.message);
    }

refresh

Settings

Member Visibility

On This Page

Constructors
Methods