Getting started overview

Integrating MojoAuth for passwordless authentication involves a series of steps, beginning with account setup and API key acquisition, followed by the implementation of client-side or server-side SDKs to manage authentication flows. The process is designed to enable developers to quickly add authentication capabilities without requiring users to create or remember passwords. MojoAuth supports various authentication methods, including magic links, one-time passwords (OTPs) sent via email or SMS, and social logins, allowing for flexible integration into different application architectures.

The core components of a MojoAuth integration include the MojoAuth Dashboard for configuration and credential management, and the chosen SDK (e.g., JavaScript, Node.js, Python) for handling the authentication logic within your application. The typical flow involves initiating a login request from the client, MojoAuth sending a verification token (e.g., magic link, OTP), the user verifying their identity, and finally, MojoAuth issuing a JSON Web Token (JWT) that your application can use to establish a secure session. This JWT-based approach is a standard for securely transmitting information between parties and is widely used in modern web applications.

This guide focuses on the essential steps to get MojoAuth operational, from initial setup to performing a basic authentication call, using the provided developer tools and documentation. Emphasis is placed on practical steps to ensure a functional setup.

Quick reference table

Step What to do Where
1. Create Account Sign up for a free MojoAuth account. MojoAuth homepage
2. Get API Keys Access the MojoAuth Dashboard to retrieve your API Key and Secret. MojoAuth Dashboard > Settings > API Keys (MojoAuth API reference)
3. Choose SDK Select the appropriate SDK for your frontend or backend environment. MojoAuth documentation > SDKs
4. Initialize SDK Configure the SDK with your API Key and other settings. Your application code
5. Implement Login Flow Integrate MojoAuth's methods (e.g., sendMagicLink, verifyOTP). Your application code
6. Handle Callbacks Process the authentication response and manage user sessions. Your application code

Create an account and get keys

To begin using MojoAuth, the initial requirement is to create an account. MojoAuth offers a "Free Forever" tier that includes up to 2,000 Monthly Active Users (MAUs), which is suitable for initial development and testing. The signup process is standard, requiring an email address and password, or authentication via a social provider.

  1. Sign Up: Navigate to the MojoAuth homepage and select the option to sign up. Follow the on-screen prompts to complete the registration.
  2. Access Dashboard: Once registered and logged in, you will be directed to the MojoAuth Dashboard. This dashboard is the central control panel for managing your applications, users, and authentication settings.
  3. Create a Project: Inside the dashboard, you may need to create a new project. Each project acts as a container for your application's authentication configuration. Give your project a descriptive name.
  4. Retrieve API Keys: Within your project settings in the MojoAuth Dashboard, locate the "API Keys" section. Here, you will find your unique API Key and API Secret. The API Key is typically used for client-side SDK initialization, while the API Secret is crucial for server-side operations and should be kept confidential. For detailed instructions on key retrieval, refer to the MojoAuth API reference documentation.
  5. Configure Redirect URLs: For security purposes, especially when using magic links or social logins, you must configure authorized redirect URLs. These URLs specify where MojoAuth should redirect users after a successful authentication attempt. This is typically found under your project's settings in the dashboard.

It is important to secure your API Secret. Never expose it in client-side code or public repositories. Treat it like a password for your application's access to MojoAuth services.

Your first request

Once you have your API Key and have configured your project, you can make your first authentication request. This example uses the MojoAuth JavaScript SDK for a client-side implementation, which is often the quickest way to demonstrate passwordless login.

Prerequisites

  • A web page (HTML file) where you can embed JavaScript.
  • Your MojoAuth API Key.

Step-by-step JavaScript SDK integration

  1. Include the MojoAuth JavaScript SDK: Add the following script tag to the <head> or before the closing </body> tag of your HTML file. This loads the SDK asynchronously.

    <script async src="https://assets.mojoauth.com/js/mojoauth.min.js"></script>

  2. Create a container for the login form: Add a <div> element in your HTML where the MojoAuth login interface will be rendered.

    <div id="mojoauth-form"></div>

  3. Initialize and render MojoAuth: Add a JavaScript block to your HTML (preferably after the container div) to initialize MojoAuth with your API Key and render the login form.

    <script>
  document.addEventListener('DOMContentLoaded', function() {
    const mojoauth = new MojoAuth('YOUR_API_KEY', {
      language: 'en',
      redirect_url: 'YOUR_REDIRECT_URL' // Optional, if not set in dashboard
    });

    mojoauth.signInWithEmailOTP().then(response => {
      // This callback is executed after successful authentication
      console.log('Authentication successful!', response);
      // The response object contains the JWT and user information.
      // You would typically send this JWT to your backend for session management.
      alert('Welcome, ' + response.user.email + '! Check console for details.');

    }).catch(error => {
      console.error('Authentication failed:', error);
      alert('Authentication failed. Please try again.');
    });
  });
</script>

    Replace 'YOUR_API_KEY' with the actual API Key obtained from your MojoAuth Dashboard.

    Replace 'YOUR_REDIRECT_URL' if you have a specific URL where you want to redirect users after authentication. This should match one of the URLs configured in your MojoAuth project settings. If not explicitly set here, MojoAuth will use the default redirect URL configured in your dashboard.

  4. Test the integration: Open your HTML file in a web browser. You should see a login form prompting for an email address. Enter an email, and MojoAuth will send an OTP. Upon entering the correct OTP, the .then() callback will execute, logging the authentication response to the console and displaying an alert.

This example demonstrates email OTP login. MojoAuth supports other methods like magic links, SMS OTP, and social logins, which can be invoked using different SDK methods (e.g., signInWithMagicLink(), signInWithPhoneOTP()). Refer to the MojoAuth official documentation for specific method calls and configuration options for each authentication type.

Common next steps

After successfully implementing a basic MojoAuth login, consider these common next steps to enhance your authentication system:

  • Backend Integration: The most crucial next step is to integrate your backend with MojoAuth. After a successful client-side authentication, MojoAuth returns a JSON Web Token (JWT). Your backend should receive this JWT, validate it, and then establish a secure session for the user. This typically involves verifying the JWT's signature and claims (e.g., expiration, issuer) using your API Secret or public keys provided by MojoAuth. Many modern web frameworks offer libraries for JWT validation.
  • User Profile Management: Once authenticated, you can retrieve additional user information from the JWT or by making a call to MojoAuth's user profile API. Store relevant user data in your application's database and manage user profiles.
  • Session Management: Implement robust session management on your backend. This involves creating and managing secure sessions (e.g., using secure, HTTP-only cookies) after JWT validation, ensuring that the user remains authenticated across requests.
  • Error Handling and UI/UX: Enhance the user experience by implementing comprehensive error handling for various authentication scenarios. Provide clear feedback to users during login, registration, and error states. Customize the appearance of the MojoAuth login widget to match your application's branding.
  • Advanced Authentication Methods: Explore and integrate other passwordless authentication methods offered by MojoAuth, such as SMS OTP, social logins (Google, Facebook), or customize magic link flows. Each method may require specific configurations in the MojoAuth Dashboard and corresponding SDK calls.
  • Webhooks: Configure webhooks in MojoAuth to receive real-time notifications about important events, such as new user registrations or authentication failures. This can be useful for triggering downstream processes or for auditing purposes.
  • Security Best Practices: Review and implement general security best practices for authentication, such as protecting against brute-force attacks, ensuring secure communication (HTTPS), and regularly auditing your authentication logs.

Troubleshooting the first call

When encountering issues with your initial MojoAuth integration, consider the following troubleshooting steps:

  • Incorrect API Key: Double-check that you have used the correct API Key from your MojoAuth Dashboard. A common mistake is using the API Secret in place of the API Key for client-side initialization.

  • Missing or Incorrect Redirect URL: If you are using magic links or have specified a redirect_url in the SDK, ensure it is correctly configured in both your code and the MojoAuth Dashboard. The URL in the dashboard must exactly match the URL where MojoAuth should redirect users post-authentication. Mismatches are a frequent source of errors.

  • Network Issues: Verify that your application can access MojoAuth's servers. Check your browser's developer console for network errors, such as failed requests to assets.mojoauth.com or MojoAuth API endpoints.

  • JavaScript Console Errors: Open your browser's developer console (F12 or Cmd+Option+J) and look for any JavaScript errors. These can indicate problems with SDK initialization, method calls, or unexpected responses.

  • Ad Blockers/Browser Extensions: Occasionally, browser extensions (like ad blockers or privacy tools) can interfere with external scripts. Try testing in an incognito/private window or with extensions disabled.

  • CORS Issues: If you are making direct API calls from a domain not configured in MojoAuth's allowed origins, you might encounter Cross-Origin Resource Sharing (CORS) errors. Ensure your domain is whitelisted in your MojoAuth project settings.

  • Check MojoAuth Dashboard Logs: The MojoAuth Dashboard usually provides logs or analytics that can offer insights into authentication attempts, successes, and failures. Review these logs for more specific error messages related to your API calls.

  • Refer to Documentation: Consult the official MojoAuth documentation for detailed error codes, troubleshooting guides, and specific integration instructions for the SDK you are using. The documentation is the most authoritative source for resolving specific integration challenges.

  • Server-Side Validation Failure: If the client-side authentication appears successful but your application isn't creating a session, the issue might be in your backend's JWT validation logic. Ensure your backend properly verifies the JWT's signature and claims, using the correct API Secret or public keys.